Back to Blog

Make your first SkillTweet API request

Create an API key, send one HTTPS request, and read the flat JSON envelope.

Every /v1/* endpoint is a plain HTTPS call. No SDK, no OAuth handshake, no wrapper library — three steps and you have data.

1. Create an API key

Sign in to SkillTweet and open Account. Create a key there, then top it up: new accounts start with a small free credit, the balance never expires, and a call that fails is never billed.

The same page shows live balance, token usage and cost, so you can watch your first calls spend.

2. Send the request

curl 'https://api.skilltweet.com/v1/tweets/search?q=AI&count=5' \
  -H 'X-API-KEY: $AGENTTWEET_API_KEY'

q speaks X search syntax — from:someone, lang:en, min_faves:100, -filter:replies — and count takes 1 to 100. If you prefer a standard auth header, Authorization: Bearer $AGENTTWEET_API_KEY works everywhere too.

3. Read the envelope

Data endpoints all return the same shape: data carries the payload, meta carries paging and token accounting.

{
  "data": [
    { "id": "…", "text": "…", "author": "…" }
  ],
  "meta": {
    "count": 5,
    "cursor": "g2AAAA…",
    "provider": "twittrapi",
    "cached": false,
    "tokens_raw": 18422,
    "tokens_flat": 5814,
    "tokens_saved": 12608,
    "tokens_saved_pct": 78.4,
    "tokens_billed": 5814,
    "cost_usd": 0.00058,
    "balance_usd": 0.4994,
    "request_id": "…"
  }
}

The numbers you actually care about:

  • meta.tokens_billed is what the call cost, in tokens. Failed calls are not billed at all.
  • meta.tokens_saved_pct is how many tokens flat JSON saved against the raw upstream payload — no math on your side.
  • meta.balance_usd is the remaining balance after this call, so an agent can stop itself before running dry.
  • meta.cursor is the page token: pass it back as cursor to fetch the next page.

The response repeats the same figures in X-Tokens-Used, X-Tokens-Remaining and X-Tokens-Saved-Percent headers, so a pipeline can read its own cost without a second round trip.

Where to go next