Skip to Content

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

GroupEndpointsWhat it does
datasearch tweets, profile, timeline, followersRead X data as flat JSON
monitorscreate/read/delete monitorsPoll an account, push new tweets to a webhook
accountaccount, usage, pricing, cacheBalance, token billing, cache hit rate
public/health, /apiService 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.