AgentTweet API Overview
The X (Twitter) data API: one envelope, API key auth, token-based pricing, 78% fewer tokens than raw JSON.
An X data API for AI agents and scripts. It returns flat JSON — cleaned, expanded, stripped of noise — which saves 78% of tokens against the upstream raw payload, and another 65.8% against other flattened formats.
Authentication
Every /v1/* endpoint needs an API key. Either header works:
curl https://api.agenttweet.com/v1/tweets/search?q=lang:zh \
-H "X-API-KEY: $AGENTTWEET_API_KEY"curl https://api.agenttweet.com/v1/tweets/search?q=lang:zh \
-H "Authorization: Bearer $AGENTTWEET_API_KEY"Failed calls are never billed
Auth failures, upstream errors, rate limits — a call that fails is not charged. The billing figure is meta.tokens_billed.
The response envelope
Every response uses the same envelope: data holds the payload, meta holds pagination and token accounting.
{
"data": [ { "id": "…", "text": "…", "author": "…" } ],
"meta": {
"count": 20,
"cursor": "g2AAAA…",
"tokens_raw": 18422,
"tokens_flat": 5814,
"tokens_saved_pct": 78.4,
"cost_usd": 0.00058
}
}meta.tokens_saved_pct is how many tokens this call saved against the raw JSON — no math on your side.
Endpoint groups
| Group | Endpoints | What it does |
|---|---|---|
data | search tweets, profile, timeline, followers | Read X data as flat JSON |
monitors | create/read/delete monitors | Poll an account, push new tweets to a webhook |
account | account, usage, pricing, cache | Balance, token billing, cache hit rate |
public | /health, /api | Service status and endpoint index, no auth |
Every operation in the sidebar has its own page with parameters and response examples.
MCP out of the box
npm i -g agenttweet-mcp{
"mcpServers": {
"agenttweet": {
"command": "npx",
"args": ["-y", "agenttweet-mcp"],
"env": { "AGENTTWEET_API_KEY": "${env:AGENTTWEET_API_KEY}" }
}
}
}Tool descriptions ship in English and Chinese.
Pricing
Billing is per token, not per call: you pay for the data a call returns. A cache hit costs zero upstream. Live prices: GET /v1/pricing and GET /v1/cache.