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_billedis what the call cost, in tokens. Failed calls are not billed at all.meta.tokens_saved_pctis how many tokens flat JSON saved against the raw upstream payload — no math on your side.meta.balance_usdis the remaining balance after this call, so an agent can stop itself before running dry.meta.cursoris the page token: pass it back ascursorto 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
- Token billing and top-up tiers explains the one-page minimum and how rolling 30-day top-ups lower your rate.
- Monitors and webhooks push new posts to your URL instead of polling.
- The API docs list every endpoint with parameters and response examples.