Skip to content

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.
your first X call
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

EndpointMethod and pathCredits
Get a userGET /v1/x/users/{handle}2 credits
Search usersGET /v1/x/users/search2 credits
Check a followGET /v1/x/users/{source}/follows/{target}2 credits
Check a usernameGET /v1/x/users/{handle}/availability2 credits
Audit followersGET /v1/x/users/{handle}/follower-audit3 credits per call (up to 40 followers sampled)
Account analyticsGET /v1/x/users/{handle}/analytics4 credits per call (latest 20 posts)
Find a locationGET /v1/x/users/{handle}/location2 credits per call

Followers

EndpointMethod and pathCredits
List followersGET /v1/x/users/{handle}/followers2 credits per page (20 rows by default)
List followingGET /v1/x/users/{handle}/following2 credits per page (20 rows by default)
List verified followersGET /v1/x/users/{handle}/verified-followers3 credits per 20 rows
Search followersGET /v1/x/users/{handle}/followers/search2 credits per page (20 rows by default)

Tweets

EndpointMethod and pathCredits
Search tweetsGET /v1/x/tweets/search2 credits
Get a tweetGET /v1/x/tweets/{id}2 credits
List user tweetsGET /v1/x/users/{handle}/tweets2 credits
List mentionsGET /v1/x/users/{handle}/mentions2 credits
List repliesGET /v1/x/tweets/{id}/replies2 credits
List retweetersGET /v1/x/tweets/{id}/retweeters2 credits

Lists

EndpointMethod and pathCredits
List members of a listGET /v1/x/lists/{id}/members2 credits

Leads

EndpointMethod and pathCredits
Find leadsGET /v1/x/leads3 credits

Actions

EndpointMethod and pathCredits
Send a DMPOST /v1/x/dm/send10 credits
Follow or unfollowPOST /v1/x/actions/follow5 credits
Like or retweetPOST /v1/x/actions/like5 credits
Post a tweetPOST /v1/x/tweets5 credits

How X inputs work

InputWhat to passExamples
HandleThe handle, with or without @levelsio, @levelsio
Tweet idThe numeric id or the full tweet URL1846312345678901234, https://x.com/user/status/1846312345678901234
List idThe numeric id from the list URL1585430245762441216
Search query qX search operators workfrom:name, to:name, "exact phrase", crm OR hubspot, -giveaway, min_faves:10, filter:links
sortOn tweet searchlatest 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

  1. Open Accounts and choose Connect an account.
  2. Either paste the auth_token and ct0 cookies 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.
  3. Copy the account id shown in the table. You pass it as accountId on every action.

Only connect accounts you own or manage. Each plan can connect a set number of accounts:

PlanConnected 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.

connect an account with its cookies
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.

send a DM
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

FieldTypeNullableDescription
idstringnoPlatform id.
handlestringnoHandle without @.
namestringnoName.
biostringyesProfile bio.
followersnumberyesFollower count.
followingnumberyesFollowing count.
tweetsnumberyesTweet count.
verifiedbooleanyesLegacy verification.
blueVerifiedbooleanyesPaid blue check.
canDmbooleanyesWhether the account accepts DMs from anyone.
protectedbooleanyesProtected (private) account.
locationstringyesProfile location.
urlstringyesWebsite in the profile.
avatarUrlstringyesAvatar image URL.
createdAtstringyesISO 8601 UTC timestamp.
profileUrlstringnoThe account's x.com profile link.
bannerUrlstringyesProfile banner image URL.
likesGivennumberyesPosts the account has liked.
mediaCountnumberyesPhotos and videos the account has posted.
pinnedTweetIdsstring[]yesIds of the account's pinned tweets, or null when the source does not say.

XTweet

FieldTypeNullableDescription
idstringnoPlatform id.
textstringnoText.
urlstringnoFull URL on the platform.
createdAtstringyesISO 8601 UTC timestamp.
langstringyesLanguage code.
likesnumberyesLikes.
retweetsnumberyesRetweets.
repliesnumberyesReplies.
quotesnumberyesQuote tweets.
viewsnumberyesViews.
bookmarksnumberyesBookmarks.
isReplybooleannoIs a reply.
inReplyToIdstringyesTweet this replies to.
conversationIdstringyesRoot tweet id of the conversation.
isRetweetbooleannoIs a retweet.
quotedTweetIdstringyesTweet this quotes.
typeenumnotweet, reply, retweet or quote.
isQuotebooleannoQuotes another tweet.
isPinnedbooleannoPinned to the author's profile.
sourcestringyesApp the tweet was posted from, when X shows it.
hasVideobooleannoHas a video or GIF.
urlsstring[]noFull (expanded) links in the text.
mentionsstring[]noHandles mentioned in the text, without @.
authorobjectnoAuthor profile (XUser).
mediaobject[]noPhotos and videos: type, url (for a video, its thumbnail) and videoUrl (the mp4, or null).
quotedTweetobjectyesThe quoted tweet, same fields as this one, or null.
retweetedTweetobjectyesThe original tweet when this is a retweet, or null. Its author is who was retweeted.

XFollowCheck

FieldTypeNullableDescription
sourcestringnoThe account that might follow.
targetstringnoThe account that might be followed.
sourceFollowsTargetbooleannoTrue when source follows target.
targetFollowsSourcebooleannoTrue when target follows source.
mutualbooleannoTrue when both follow each other.
canDmbooleanyesWhether X lets source send target a DM, as X reports it for this pair. Null when X does not say.

XUsernameCheck

FieldTypeNullableDescription
handlestringnoHandle without @.
statusenumno
likelyAvailablebooleanno
idstringyesPlatform id.
createdAtstringyesISO 8601 UTC timestamp.
notestringno

XFollowerAudit

FieldTypeNullableDescription
handlestringnoHandle without @.
samplednumberno
suspiciousnumberno
suspiciousSharenumberno
inactivenumberno
signalsobjectno
accountsobject[]no
notestringno

XAccountAnalytics

FieldTypeNullableDescription
handlestringnoHandle without @.
namestringnoName.
followersnumberyesFollower count.
followingnumberyesFollowing count.
totalPostsnumberyes
joinedstringyes
verifiedbooleannoLegacy verification.
samplednumberno
spanDaysnumberno
postsPerDaynumberyes
avgLikesnumberno
avgRepliesnumberno
avgRepostsnumberno
avgViewsnumberyes
engagementRatenumberyes
mixobjectno
busiestHourUtcnumberyes
topPostobjectyes
asOfstringno
notestringno

XUserLocation

FieldTypeNullableDescription
handlestringnoHandle without @.
namestringnoName.
locationstringyesProfile location.
hasLocationbooleanno
notestringno

XWriteResult

FieldTypeNullableDescription
okbooleannoAlways true on success.
actionenumnoWhat was done.
accountIdstringnoConnected account that acted.
targetIdstringyesTarget user or tweet id.
resultIdstringyesId of what was created, if any.
dryRunbooleannoTrue when nothing was sent.

Lead

FieldTypeNullableDescription
platformenumnoreddit or x.
kindenumnopost, comment or tweet.
idstringnoPlatform id.
urlstringnoFull URL on the platform.
textstringnoText.
authorstringyesAuthor username. Empty (or null) when the account was deleted.
authorUrlstringyesAuthor profile URL.
communitystringyesSubreddit for Reddit items, null for X.
scorenumberyesEngagement score: Reddit upvotes minus downvotes for Reddit items, likes for X items.
createdAtstringyesISO 8601 UTC timestamp.
intentenumnoasking_for_recommendation, comparing_tools, complaining_about_tool or other.
intentScorenumbernoIntent score from 0 to 1.
matchedTermsstring[]noPhrases 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

CodeWhenWhat to do
not_foundThe handle, tweet or list doesn't exist or is private.Check the input. Don't retry.
x_account_requiredNo connected account has that accountId, or it's paused.Connect or resume the account and pass its id.
x_account_needs_reconnectThe account's X session ended.Reconnect it on the Accounts page, or with POST /v1/x/accounts and reconnectId. Don't retry.
rate_limitedYour key's request rate, or the account's daily action limit.Wait for Retry-After.
invalid_inputA bad parameter, a missing Idempotency-Key, or X refused the action (a duplicate tweet, for example).Read the message and fix the request.
upstream_timeoutX didn't answer in time.For actions, check whether it went through before you resend.

Every code, with response bodies, is on Errors.