X API
Updated
Read X (Twitter) data and act from X accounts you connect, through one REST API or the hosted MCP server. You don't need an X developer account.
Overview
Base URL: https://api.chatterapi.com/v1. X endpoints sit under /v1/x, and every call needs your key in the Authorization: Bearer header. The MCP server at https://api.chatterapi.com/mcp exposes the same endpoints as tools.
- Reads cost 2 credits per call or per page of about 20 rows, and need nothing but your key.
- Actions (DMs, follows, likes, retweets and tweets) run from X accounts you connect on the Accounts page. They are never sent from shared accounts.
- Test keys (
ca_test_...) return recorded samples for reads. For actions they do a dry run, so nothing is sent and nothing is charged.
curl "https://api.chatterapi.com/v1/x/users/levelsio" \
-H "Authorization: Bearer $CHATTERAPI_KEY"Endpoints by chapter
Each endpoint has its own page with parameters, request samples in curl, JavaScript, Python and MCP, a recorded response and the errors it can return. You're charged for an action only when X accepts it.
Users
| Endpoint | Method and path | Credits |
|---|---|---|
| Get a user | GET /v1/x/users/{handle} | 2 credits |
| Search users | GET /v1/x/users/search | 2 credits |
| Check a follow | GET /v1/x/users/{source}/follows/{target} | 2 credits |
| Check a username | GET /v1/x/users/{handle}/availability | 2 credits |
| Audit followers | GET /v1/x/users/{handle}/follower-audit | 3 credits per call (up to 40 followers sampled) |
| Account analytics | GET /v1/x/users/{handle}/analytics | 4 credits per call (latest 20 posts) |
| Find a location | GET /v1/x/users/{handle}/location | 2 credits per call |
Followers
| Endpoint | Method and path | Credits |
|---|---|---|
| List followers | GET /v1/x/users/{handle}/followers | 2 credits per page (20 rows by default) |
| List following | GET /v1/x/users/{handle}/following | 2 credits per page (20 rows by default) |
| List verified followers | GET /v1/x/users/{handle}/verified-followers | 3 credits per 20 rows |
| Search followers | GET /v1/x/users/{handle}/followers/search | 2 credits per page (20 rows by default) |
Tweets
| Endpoint | Method and path | Credits |
|---|---|---|
| Search tweets | GET /v1/x/tweets/search | 2 credits |
| Get a tweet | GET /v1/x/tweets/{id} | 2 credits |
| List user tweets | GET /v1/x/users/{handle}/tweets | 2 credits |
| List mentions | GET /v1/x/users/{handle}/mentions | 2 credits |
| List replies | GET /v1/x/tweets/{id}/replies | 2 credits |
| List retweeters | GET /v1/x/tweets/{id}/retweeters | 2 credits |
Lists
| Endpoint | Method and path | Credits |
|---|---|---|
| List members of a list | GET /v1/x/lists/{id}/members | 2 credits |
Leads
| Endpoint | Method and path | Credits |
|---|---|---|
| Find leads | GET /v1/x/leads | 3 credits |
Actions
| Endpoint | Method and path | Credits |
|---|---|---|
| Send a DM | POST /v1/x/dm/send | 10 credits |
| Follow or unfollow | POST /v1/x/actions/follow | 5 credits |
| Like or retweet | POST /v1/x/actions/like | 5 credits |
| Post a tweet | POST /v1/x/tweets | 5 credits |
How X inputs work
| Input | What to pass | Examples |
|---|---|---|
| Handle | The handle, with or without @ | levelsio, @levelsio |
| Tweet id | The numeric id or the full tweet URL | 1846312345678901234, https://x.com/user/status/1846312345678901234 |
| List id | The numeric id from the list URL | 1585430245762441216 |
Search query q | X search operators work | from:name, to:name, "exact phrase", crm OR hubspot, -giveaway, min_faves:10, filter:links |
sort | On tweet search | latest for monitoring, top for the most-engaged tweets |
Pages of about 20
Follower, following, timeline, search, reply, retweeter and list endpoints return about 20 rows a page. X decides the exact count. Pass page.nextCursor back as cursor until page.hasMore is false. Large accounts have many pages, so set a page budget in your code.
Can this account receive a DM?
User objects include canDm when X reports it, and null when it doesn't. Filter on it before you spend credits on x.dm_send.
Actions: connect an account first
- Open Accounts and choose Connect an account.
- Either paste the
auth_tokenandct0cookies from a browser where you're logged into that X account, or log in with its username and password (plus the 2FA setup key if it has one). We encrypt what you send before storing it and never log it. - Copy the account id shown in the table. You pass it as
accountIdon every action.
Only connect accounts you own or manage. Each plan can connect a set number of accounts:
| Plan | Connected X accounts |
|---|---|
| Free (signup credits only) | 1 |
| Starter ($19/month) | 2 |
| Growth ($49/month) | 10 |
| Scale ($149/month) | 40 |
Connect accounts from your own code
If you build a product on ChatterAPI, your users can connect their own X accounts without going through our dashboard. Call POST /v1/x/accounts with a key that has write access and send either the account's auth_token, ct0 and twid cookies or its username and password. You get back the account id, which you pass as accountId on actions. GET /v1/x/accounts lists the connected accounts and flags any that need reconnecting, and DELETE /v1/x/accounts/{id} disconnects one. All three are free. Test keys get a dry run: we check the request and answer it, but nothing is sent to X or stored.
curl -X POST "https://api.chatterapi.com/v1/x/accounts" \
-H "Authorization: Bearer $CHATTERAPI_KEY" \
-H "Content-Type: application/json" \
-d '{"method":"cookies","authToken":"YOUR_AUTH_TOKEN","ct0":"YOUR_CT0","twid":"YOUR_TWID"}'We encrypt whatever you send before we store it. We never log it and never send it back. Each X account your plan allows gets 10 connect attempts an hour, and failed attempts count toward that. Your plan's account limit (table above) still applies: if you are already at it, we refuse the new account before contacting X. We tell accounts apart by the user id inside the twid cookie, so pass the cookies exactly as the person copied them. A failed connect returns a reason such as wrong_credentials, needs_2fa, locked, cookies_rejected, limit or already_connected, which lets your code tell the person what to fix.
When an action returns x_account_needs_reconnect, call POST /v1/x/accounts again with the person's fresh cookies or login and set reconnectId to that account's id. The id stays the same, so you don't need to update anything else. Connecting an account that is already connected without reconnectId returns already_connected, and GET /v1/x/accounts gives you the id to use. To keep automatic re-login, reconnect with method set to login and autoRelogin set to true. Reconnecting with cookies always turns it off.
Every action needs an Idempotency-Key
Send a unique Idempotency-Key header (a UUID works) with each action. If the same key arrives again, for example when your code retries after a timeout, you get the first response back and nothing is sent or charged twice. Reusing a key for a different request returns invalid_input. Over MCP, pass the same value as the idempotencyKey argument instead of a header.
curl -X POST "https://api.chatterapi.com/v1/x/dm/send" \
-H "Authorization: Bearer $CHATTERAPI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"accountId":"YOUR_ACCOUNT_ID","recipientHandle":"jack","text":"Hi Jack, quick question about your API."}'Safety limits
Each connected account has one daily limit for DMs and a separate one for other actions, which keeps it inside what X tolerates. Past the limit, calls return rate_limited with a Retry-After pointing at 00:00 UTC, when the limits reset. Spread bulk work across days and don't loop on that error.
When a session ends
X ends sessions from time to time. When it does, actions from that account return x_account_needs_reconnect until you reconnect it on the Accounts page or with POST /v1/x/accounts and reconnectId. Accounts connected by login can turn on automatic re-login. Cookie sessions always need a manual reconnect.
Timeouts
If X doesn't answer in time you get upstream_timeout and no charge. The action may still have gone through, so check (for example with x.tweets or the DM inbox) before you send a new request with a new key.
Response objects
These are the objects inside data. Actions return XWriteResult, with dryRun: true when nothing was sent (test keys).
XUser
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | Platform id. |
handle | string | no | Handle without @. |
name | string | no | Name. |
bio | string | yes | Profile bio. |
followers | number | yes | Follower count. |
following | number | yes | Following count. |
tweets | number | yes | Tweet count. |
verified | boolean | yes | Legacy verification. |
blueVerified | boolean | yes | Paid blue check. |
canDm | boolean | yes | Whether the account accepts DMs from anyone. |
protected | boolean | yes | Protected (private) account. |
location | string | yes | Profile location. |
url | string | yes | Website in the profile. |
avatarUrl | string | yes | Avatar image URL. |
createdAt | string | yes | ISO 8601 UTC timestamp. |
profileUrl | string | no | The account's x.com profile link. |
bannerUrl | string | yes | Profile banner image URL. |
likesGiven | number | yes | Posts the account has liked. |
mediaCount | number | yes | Photos and videos the account has posted. |
pinnedTweetIds | string[] | yes | Ids of the account's pinned tweets, or null when the source does not say. |
XTweet
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | Platform id. |
text | string | no | Text. |
url | string | no | Full URL on the platform. |
createdAt | string | yes | ISO 8601 UTC timestamp. |
lang | string | yes | Language code. |
likes | number | yes | Likes. |
retweets | number | yes | Retweets. |
replies | number | yes | Replies. |
quotes | number | yes | Quote tweets. |
views | number | yes | Views. |
bookmarks | number | yes | Bookmarks. |
isReply | boolean | no | Is a reply. |
inReplyToId | string | yes | Tweet this replies to. |
conversationId | string | yes | Root tweet id of the conversation. |
isRetweet | boolean | no | Is a retweet. |
quotedTweetId | string | yes | Tweet this quotes. |
type | enum | no | tweet, reply, retweet or quote. |
isQuote | boolean | no | Quotes another tweet. |
isPinned | boolean | no | Pinned to the author's profile. |
source | string | yes | App the tweet was posted from, when X shows it. |
hasVideo | boolean | no | Has a video or GIF. |
urls | string[] | no | Full (expanded) links in the text. |
mentions | string[] | no | Handles mentioned in the text, without @. |
author | object | no | Author profile (XUser). |
media | object[] | no | Photos and videos: type, url (for a video, its thumbnail) and videoUrl (the mp4, or null). |
quotedTweet | object | yes | The quoted tweet, same fields as this one, or null. |
retweetedTweet | object | yes | The original tweet when this is a retweet, or null. Its author is who was retweeted. |
XFollowCheck
| Field | Type | Nullable | Description |
|---|---|---|---|
source | string | no | The account that might follow. |
target | string | no | The account that might be followed. |
sourceFollowsTarget | boolean | no | True when source follows target. |
targetFollowsSource | boolean | no | True when target follows source. |
mutual | boolean | no | True when both follow each other. |
canDm | boolean | yes | Whether X lets source send target a DM, as X reports it for this pair. Null when X does not say. |
XUsernameCheck
| Field | Type | Nullable | Description |
|---|---|---|---|
handle | string | no | Handle without @. |
status | enum | no | |
likelyAvailable | boolean | no | |
id | string | yes | Platform id. |
createdAt | string | yes | ISO 8601 UTC timestamp. |
note | string | no |
XFollowerAudit
| Field | Type | Nullable | Description |
|---|---|---|---|
handle | string | no | Handle without @. |
sampled | number | no | |
suspicious | number | no | |
suspiciousShare | number | no | |
inactive | number | no | |
signals | object | no | |
accounts | object[] | no | |
note | string | no |
XAccountAnalytics
| Field | Type | Nullable | Description |
|---|---|---|---|
handle | string | no | Handle without @. |
name | string | no | Name. |
followers | number | yes | Follower count. |
following | number | yes | Following count. |
totalPosts | number | yes | |
joined | string | yes | |
verified | boolean | no | Legacy verification. |
sampled | number | no | |
spanDays | number | no | |
postsPerDay | number | yes | |
avgLikes | number | no | |
avgReplies | number | no | |
avgReposts | number | no | |
avgViews | number | yes | |
engagementRate | number | yes | |
mix | object | no | |
busiestHourUtc | number | yes | |
topPost | object | yes | |
asOf | string | no | |
note | string | no |
XUserLocation
| Field | Type | Nullable | Description |
|---|---|---|---|
handle | string | no | Handle without @. |
name | string | no | Name. |
location | string | yes | Profile location. |
hasLocation | boolean | no | |
note | string | no |
XWriteResult
| Field | Type | Nullable | Description |
|---|---|---|---|
ok | boolean | no | Always true on success. |
action | enum | no | What was done. |
accountId | string | no | Connected account that acted. |
targetId | string | yes | Target user or tweet id. |
resultId | string | yes | Id of what was created, if any. |
dryRun | boolean | no | True when nothing was sent. |
Lead
| Field | Type | Nullable | Description |
|---|---|---|---|
platform | enum | no | reddit or x. |
kind | enum | no | post, comment or tweet. |
id | string | no | Platform id. |
url | string | no | Full URL on the platform. |
text | string | no | Text. |
author | string | yes | Author username. Empty (or null) when the account was deleted. |
authorUrl | string | yes | Author profile URL. |
community | string | yes | Subreddit for Reddit items, null for X. |
score | number | yes | Engagement score: Reddit upvotes minus downvotes for Reddit items, likes for X items. |
createdAt | string | yes | ISO 8601 UTC timestamp. |
intent | enum | no | asking_for_recommendation, comparing_tools, complaining_about_tool or other. |
intentScore | number | no | Intent score from 0 to 1. |
matchedTerms | string[] | no | Phrases that made this a lead. |
Recipes
Build an outreach list from a competitor's followers
Page through /v1/x/users/{handle}/followers (2 credits a page) and keep the rows where canDm is true and the bio fits. Then send each person a short, specific DM from a connected account, each with its own Idempotency-Key. Spread the sends over days to stay inside the safety limits.
Warm up before a DM
Like one of the person's recent tweets with /v1/x/actions/like and follow them with /v1/x/actions/follow before you send the DM. Both cost less than the DM, and a name they recognise gets read more often.
Monitor a brand on X
Call /v1/x/tweets/search?q=yourbrand&sort=latest on a schedule, then /v1/x/users/{handle}/mentions for tagged mentions. To catch Reddit too, use the cross-platform Brand Mentions endpoint.
Let an agent do it
Add the MCP server (see MCP) and ask in plain words, for example: "find people asking for a CRM on X this week and draft a DM to the three best fits". The agent sees what each action tool costs and needs your account id to act.
Errors you'll see
| Code | When | What to do |
|---|---|---|
not_found | The handle, tweet or list doesn't exist or is private. | Check the input. Don't retry. |
x_account_required | No connected account has that accountId, or it's paused. | Connect or resume the account and pass its id. |
x_account_needs_reconnect | The account's X session ended. | Reconnect it on the Accounts page, or with POST /v1/x/accounts and reconnectId. Don't retry. |
rate_limited | Your key's request rate, or the account's daily action limit. | Wait for Retry-After. |
invalid_input | A bad parameter, a missing Idempotency-Key, or X refused the action (a duplicate tweet, for example). | Read the message and fix the request. |
upstream_timeout | X didn't answer in time. | For actions, check whether it went through before you resend. |
Every code, with response bodies, is on Errors.