# TwitterAPIs - Complete Reference

> TwitterAPIs is the cheapest pay-as-you-go Twitter/X data API at $0.0008 per API call, which is $0.04 per 1,000 tweets when a call returns a full 20-tweet page. Fetch tweets, user profiles, followers, following, search, mentions, media, bookmarks, likes, the home timeline, and DMs, plus write actions (post, like, retweet, bookmark, follow, and send a DM). No subscriptions, no developer account needed.

## What is TwitterAPIs?

TwitterAPIs is a third-party Twitter/X data API designed for developers, researchers, and businesses who need access to Twitter data without the complexity and cost of the official X API. It provides a simple REST API with pay-per-call pricing at $0.0008 per request (~20 tweets per call), making it about $0.04 per 1,000 tweets on a full 20-tweet page. The 20 is the default page size we request, not a guaranteed yield, so a thin page costs the same $0.0008 and lifts the real per-1,000 figure.

Key advantages:
- 112 endpoints: 68 reads and 44 writes
- No official X developer account required
- No monthly subscriptions or locked tiers
- Pay only for what you use
- Each call returns ~20 tweets, so $0.04 per 1,000 tweets
- $0.50 free credits on signup (no credit card)
- Response time under 2 seconds
- 99.9% uptime SLA
- No platform-level rate caps

## Pricing

TwitterAPIs uses usage-based pricing.

### Standard Endpoints ($0.0008 per call, ~20 tweets per call)
These include the tweet, user, search, and list endpoints:
- GET /twitter/tweet/advanced_search
- GET /twitter/tweet/detail
- GET /twitter/tweet/replies
- GET /twitter/tweet/retweeters
- GET /twitter/tweet/quotes (the tweets that quote a tweet; search-backed, so count is what the search returned, not the tweet's quote_count)
- GET /twitter/tweet/thread (full thread expansion, $0.004 per call)
- GET /twitter/user/search
- GET /twitter/user/info
- GET /twitter/user/info_by_id
- GET /twitter/user/status
- GET /twitter/user/user_about
- GET /twitter/user/user_about/batch ($0.0008 per item, not per call: up to 100 accounts' About data per request)
- GET /twitter/user/followers
- GET /twitter/user/followers_v2
- GET /twitter/user/following
- GET /twitter/user/following_v2
- GET /twitter/user/verified_followers
- GET /twitter/user/media
- GET /twitter/user/tweets
- GET /twitter/user/tweets_and_replies
- GET /twitter/user/mentions
- GET /twitter/user/check_follow_relationship
- GET /twitter/user/check_follow_relationship/batch ($0.0008 per item, not per call: one account against up to 100 others, either direction)
- GET /twitter/user/audience_summary ($0.0008 per item, not per call: country histogram and likely-bot share over a sample of up to 100 followers or retweeters)
- GET /twitter/user/affiliates
- GET /twitter/user/followers_you_know
- GET /twitter/user/likes
- GET /twitter/user/home_timeline (authenticated session)
- GET /twitter/user/bookmarks (authenticated session)
- GET /twitter/user/bookmark_search (authenticated session)
- GET /twitter/user/bookmark_folders (authenticated session, your own bookmark folders)
- GET /twitter/user/bookmark_folder_timeline (authenticated session, tweets inside one of your bookmark folders)
- GET /twitter/user/blocking (authenticated session, your own blocked accounts)
- GET /twitter/user/muting (authenticated session, your own muted accounts)
- GET /twitter/user/tweets/complete (full account history, $0.0024 per call)
- GET /twitter/list/members
- GET /twitter/list/followers (the accounts that follow a public List, a different set from its members)
- GET /twitter/list/tweets (a public List's posts from X's search index, filterable by date and replies, no retweets)
- GET /twitter/list/timeline (a public List's native X feed, members' retweets and X's own ordering included, no filters)
- GET /twitter/trends
- GET /twitter/trends/locations
- GET /twitter/spaces/info (X Space metadata and participant roster, live or ended)
- GET /twitter/community/search (find communities by keyword; the discovery step that produces a community id)
- GET /twitter/community/info (one X Community's metadata, rules, policies and banners)
- GET /twitter/community/members (a community's member roster, each row carrying that member's own role)
- GET /twitter/community/moderators (a community's moderators and admins, from a dedicated upstream operation)
- GET /twitter/community/about (a community's moderators plus a members preview, both as FULL user profiles)
- GET /twitter/community/tweets (a community's post timeline, with the pinned post returned separately)
- GET /twitter/community/memberships (every community a given numeric user id belongs to)
- POST /twitter/user/user_login (mint a session from credentials)

### Direct Messages (authenticated session)
- GET /twitter/dm/list (read, $0.0016 per call)
- GET /twitter/dm/conversation (read, $0.0016 per call)
- POST /twitter/dm/send (write, $0.0016 per call)

### Articles (authenticated session, except article/get which is a public read)
- POST /twitter/article/create (write, $0.0016 per call)
- POST /twitter/article/update_title (write, $0.0016 per call)
- POST /twitter/article/update_content (write, $0.0016 per call)
- POST /twitter/article/update_cover_media (write, $0.0016 per call, attaches an already-uploaded image as the article cover)
- POST /twitter/article/publish (write, $0.0016 per call, posts a real public announcement tweet)
- POST /twitter/article/unpublish (write, $0.0016 per call)
- GET /twitter/article/get (public read, no session required, $0.0008 per call)
- GET /twitter/article/list (read, your own articles, $0.0008 per call)
- POST /twitter/article/delete (write, $0.0008 per call)

### Grok (authenticated session)
- POST /twitter/grok/chat (write, $0.0040 per call, ask X's in-app Grok and get the answer plus its citations)
- GET /twitter/grok/config (read, free, your account's Grok eligibility and model options)

### Drafts and Scheduled Posts (authenticated session)
A draft is PRIVATE and never posts. A scheduled post WILL publish at its execute_at unless it is cancelled first. Both lists read only the caller's own account.
- POST /twitter/draft/create (write, $0.0016 per call, save a private draft; nothing is posted)
- POST /twitter/draft/edit (write, $0.0016 per call, replace an existing draft's contents)
- POST /twitter/draft/delete (write, $0.0008 per call, remove a draft)
- GET /twitter/draft/list (read, $0.0016 per call, your own drafts, newest first)
- POST /twitter/scheduled/create (write, $0.0016 per call, execute_at is epoch SECONDS in the future)
- POST /twitter/scheduled/delete (write, $0.0008 per call, cancel a scheduled post before it sends)
- GET /twitter/scheduled/list (read, $0.0016 per call, your pending queue, execute_at returned in epoch seconds)

### Free Account Endpoints ($0 per call)
- GET /account/me
- GET /account/payments
- POST /feedback (send product feedback from your AI agent: bug, idea, or missing capability)
- GET /feedback/{id} (read back a report's status and the team's reply)
- GET /feedback (list the reports your account has filed, newest first, cursor-paged)
- POST /twitter/customer/session (register your X session cookies)
- POST /twitter/customer/session/delete (revoke your own stored session cookies)
- GET /twitter/customer/session/status (read back your own registered session: resolved account, live or dead, and whether your proxy is in use)

### Cost Examples
Each API call returns up to ~20 tweets, so the effective cost is $0.04 per 1,000 tweets on a full page:
- 1,000 API calls = $0.80 (~20,000 tweets)
- 10,000 API calls = $8 (~200,000 tweets)
- 100,000 API calls = $80 (~2,000,000 tweets)

## Pricing Comparison vs Competitors

### vs Official X API (Pay-Per-Use)
- Official X reads: $0.005 to $0.010 per resource (1 item per request)
- Official X writes: $0.010 to $0.015 per request
- TwitterAPIs: $0.0008/call (~20 tweets), so $0.04 per 1,000 tweets vs $5 to $10 on official API

### vs twitterapi.io
- twitterapi.io: $0.15 per 1,000 tweets (~20 tweets per call)
- TwitterAPIs: $0.04 per 1,000 tweets (~20 tweets per call), 3.75x cheaper

### vs Other Third-Party APIs
- Most charge $49+/month with subscriptions
- TwitterAPIs has no subscriptions, pure pay-per-use

## API Endpoints - Detailed

### Tweet Endpoints

**Advanced Search**
- Endpoint: GET /twitter/tweet/advanced_search
- Search tweets with filters, operators, date ranges
- Price: $0.0008/call

**Tweet Detail**
- Endpoint: GET /twitter/tweet/detail
- Get full tweet data including engagement metrics
- Price: $0.0008/call

**Tweet Replies**
- Endpoint: GET /twitter/tweet/replies
- Get conversation replies to a specific tweet
- Price: $0.0008/call

**Tweet Retweeters**
- Endpoint: GET /twitter/tweet/retweeters
- Get the list of users who reposted (retweeted) a tweet (~20 users/page)
- Price: $0.0008/call

**Tweet Quotes**
- Endpoint: GET /twitter/tweet/quotes
- Page through the tweets that quote a given tweet, by id or url, as full tweet objects, so you can read the commentary rather than only count it
- SEARCH-BACKED: X exposes no dedicated quote-tweets operation, so this runs the search query quoted_tweet_id:<id> against X's search index. The count field is what that search returned, never the tweet's authoritative total, which is quote_count on the tweet object from GET /twitter/tweet/detail. The two will differ: a quote posted seconds ago may not be indexed yet, and deleted, protected, suspended and region-withheld quotes are absent from the index entirely. Treat count as a floor on what is publicly readable
- Every response says so in-band: source is always "search", search_query is the exact query sent upstream, and quote_matched is how many returned rows demonstrably carry the requested tweet as their quoted_tweet. quote_matched equal to count means every row is a genuine quote; quote_matched of 0 on a non-empty page means X stopped honouring the operator and the rows are junk
- An empty first Top page is served from Latest instead of reading as zero quotes: product_used says which ordering served the page, and top_fallback is true when the switch happened. Keep paging with next_cursor as usual; after a fallback it stays on Latest.
- The four search-backed reads (tweet/advanced_search, tweet/quotes, user/mentions, list/tweets) mark a page X soft-limited with incomplete: true, incomplete_reason "upstream_soft_limit" and upstream_limit (X's codes and message). A page without incomplete is complete.
- Optional strict=true drops non-matching rows instead of only counting them, and is metered on the rows you actually receive. Off by default, because X does not embed the quoted original on every search result
- Price: $0.0008/call

**Tweet Thread**
- Endpoint: GET /twitter/tweet/thread
- Resolve a full linear self-thread from any tweet in it (walks the original author's linked replies)
- Price: $0.004/call (full thread expansion)

### User Endpoints

**User Search**
- Endpoint: GET /twitter/user/search
- Search for users by display name or handle, X's People search (~20 users/page; bio text is not matched)
- Price: $0.0008/call

**User Info**
- Endpoint: GET /twitter/user/info
- Get user profile data by username
- Price: $0.0008/call

**User Info by ID**
- Endpoint: GET /twitter/user/info_by_id
- Get user profile data by numeric Twitter ID
- Price: $0.0008/call

**User Status**
- Endpoint: GET /twitter/user/status
- Check whether an account is alive, suspended, or deleted. Every outcome is a 200; branch on the status field
- Price: $0.0008/call

**User About**
- Endpoint: GET /twitter/user/user_about
- Get extended user details and account metadata
- Price: $0.0008/call

**User About Batch**
- Endpoint: GET /twitter/user/user_about/batch
- The same About object as User About (account country account_based_in, how the account was created, username-change history, verification and the rest) for up to 100 accounts in one request. Pass usernames or user_ids, comma-separated, never both; duplicates are removed first. Results come back in request order, each with its about object or an error code: not_found (X confirmed no such account; billed), forbidden (X refuses this account to every caller; free, retrying will not help), rate_limited or unavailable (failed on our side; free, safe to retry). One batch per API key runs at a time; a second concurrent batch gets 429 batch_in_progress and is not billed. Takes fields and compact like every read, applied inside each item's about object (fields=account_based_in)
- Price: $0.0008 per billed item, our-side failures free. Billed per account X answered for (found or not_found), so a 100-item batch costs at most $0.08

**Followers**
- Endpoint: GET /twitter/user/followers
- Get paginated list of a user's followers (REST, ~70/page)
- Price: $0.0008/call

**Followers v2**
- Endpoint: GET /twitter/user/followers_v2
- Get paginated list of a user's followers (GraphQL, ~70/page, includes canDm)
- Price: $0.0008/call

**Following**
- Endpoint: GET /twitter/user/following
- Get paginated list of accounts a user follows (REST, ~70/page)
- Price: $0.0008/call

**Following v2**
- Endpoint: GET /twitter/user/following_v2
- Get paginated list of accounts a user follows (GraphQL, ~70/page, includes canDm)
- Price: $0.0008/call

**Verified Followers**
- Endpoint: GET /twitter/user/verified_followers
- Get only verified/premium followers of a user
- Price: $0.0008/call

**User Media**
- Endpoint: GET /twitter/user/media
- Get a user's media posts (images, videos)
- Price: $0.0008/call

**User Tweets**
- Endpoint: GET /twitter/user/tweets
- Get a user's tweet timeline
- Price: $0.0008/call

**User Tweets and Replies**
- Endpoint: GET /twitter/user/tweets_and_replies
- Get tweets including replies
- Price: $0.0008/call

**User Mentions**
- Endpoint: GET /twitter/user/mentions
- Get tweets mentioning a user
- Price: $0.0008/call

**Check Follow Relationship**
- Endpoint: GET /twitter/user/check_follow_relationship
- Check if one user follows another: following, followed_by, block, mute and DM-eligibility flags. Pass each side as a numeric ID (source_user_id, target_user_id) or a username (source_username, target_username); an unknown username returns a 404 that is not billed
- Price: $0.0008/call

**Check Follow Relationship Batch**
- Endpoint: GET /twitter/user/check_follow_relationship/batch
- One account against up to 100 others in one request: one source (source_user_id or source_username) with up to 100 targets (target_usernames or target_user_ids), or one target (target_user_id or target_username) with up to 100 sources (source_usernames or source_user_ids). Each item carries the same relationship object as Check Follow Relationship, read from the source's side, or an error code: not_found (not billed), forbidden (not billed, retrying will not help), rate_limited or unavailable (failed on our side; not billed, safe to retry). One batch per API key runs at a time
- Price: $0.0008 per pair answered with a relationship, not per call, so 100 pairs cost at most $0.08; not_found and our-side failures free

**Audience Summary**
- Endpoint: GET /twitter/user/audience_summary
- Samples up to 100 of an account's followers (username or user_id) or of a tweet's retweeters (tweet_id), reads each sampled account's About object, and returns a country histogram of account_based_in plus a likely-bot share: accounts showing 3 or more of 7 documented profile signals. A heuristic over profile fields, not a verdict on any account. sample is 10 to 100, default 50, and is the first accounts X returns, not a random draw
- Price: $0.0008 per item, not per call: each sample page that added accounts (at most 3) plus each sampled account X answered About for. The balance needs room for the sample size plus 3 before any sample page is read

**User Affiliates**
- Endpoint: GET /twitter/user/affiliates
- Get affiliated accounts of a verified organization (companies, brands, nonprofits)
- Returns ~20 users per page with cursor pagination
- Price: $0.0008/call

### List Endpoints

**List Members**
- Endpoint: GET /twitter/list/members
- Get members of a Twitter list
- Price: $0.0008/call

**List Followers**
- Endpoint: GET /twitter/list/followers
- The accounts that follow a public List, cursor-paginated. Followers are not members: members are the accounts the owner added, followers are the accounts that subscribed to read it, and the two counts are unrelated. One captured List carried 557 members against 7 followers, so a small count is the normal shape and not a truncated page
- next_cursor is null once X marks the roster complete, so paging ends on a null cursor rather than on an empty page. The user objects are full profiles, the same shape user/info returns
- Price: $0.0008/call

**List Tweets**
- Endpoint: GET /twitter/list/tweets
- A public List's posts from X's search index. Filterable with since and until (YYYY-MM-DD, day granularity, until exclusive) and include_replies. No retweets, and X's search index lags new posts, so the result will not match what x.com shows for the same List
- Price: $0.0008/call

**List Timeline**
- Endpoint: GET /twitter/list/timeline
- A public List's native X feed: members' retweets and X's own ordering included. Takes only list_id, count and cursor. No date or reply filter exists on this operation, and none is faked on top of it. This and List Tweets are two capabilities, not two spellings of one
- Price: $0.0008/call

**Create List**
- Endpoint: POST /twitter/list/create
- Create a List on the account behind your registered session, with a name plus an optional description and is_private flag. Returns the new list_id, which is the proof the create landed and the ID every other List endpoint takes. Public unless is_private is set
- Price: $0.0016/call

**Add List Member**
- Endpoint: POST /twitter/list/add_member
- Add an account to your own List by numeric list_id and user_id, running as your registered session rather than a pool account. Returns member_count as proof the write landed; a write that did not apply returns the same field layout with a 422 and a machine-readable reason
- Price: $0.0008/call

**Remove List Member**
- Endpoint: POST /twitter/list/remove_member
- Remove an account from your own List by numeric list_id and user_id, running as your registered session. Returns member_count as proof the write landed, one lower than the add that preceded it
- Price: $0.0008/call

### Community Endpoints
X Communities. All five are PUBLIC POOLED READS, served by our account pool rather than by your session, exactly like a tweet or a Space lookup. That is why role, can_join, is_pinned and viewer_relationship_type come back null on every community object: each of those describes the account that made the upstream call, and on a pooled read that account is not you. The keys are kept rather than removed so it stays visible that X sends them and we decline to answer them. members[].role on a roster row is a DIFFERENT field and is NOT nulled: it describes that member, is identical for every caller, and is the reason the member roster exists.

**Community Search**
- Endpoint: GET /twitter/community/search
- Find communities by keyword, cursor-paginated. This searches COMMUNITIES, not posts, and it is the discovery step the rest of the community family assumes: every other community endpoint starts from a community id, and this is the one that produces one
- Each hit is a COMPACT record (id, name, member_count, is_nsfw, primary_topic, banner_url, custom_banner, default_banner, member_avatar_urls), not the full Community object community/info returns. primary_topic.topic_id is commonly null while primary_topic.name is populated, so key off name
- Price: $0.0008/call

**Community Info**
- Endpoint: GET /twitter/community/info
- Look up one X Community by its numeric community_id (the digits in a x.com/i/communities/<id> URL): name, description, member and moderator counts, join and invite policies, join question, primary topic, search tags, posted rules, both banners, permalink, admin and creator profiles, and the facepile member ids
- rules[].description is null on every rule, because X sends only the rule id and name on this surface. created_at is a millisecond-epoch number, not an ISO string. Both banners are always present, so read banner_url unless you specifically want one or the other
- Returns members_facepile_ids only, never the roster. Use community/members for that
- Price: $0.0008/call

**Community Members**
- Endpoint: GET /twitter/community/members
- Page through a community's member roster, each row a { user, role } pair where role is that member's own role in the community: Admin, Moderator or Member
- The user object is deliberately REDUCED (id, username, name, profile_image_url, is_blue_verified, verified, is_protected) because X's roster operation sends no bio, no follower or following counts and no created_at. Those keys are absent rather than null, so not-asked-for can never be read as zero. Call user/info on an id for the full profile
- This is a SLICE, not a running timeline, despite the upstream operation name. Paging is a bare next_cursor string: X sends no total and no has_more of its own, so has_more is computed for you from whether the page had rows and carried a usable cursor. An empty first page is a 404; an empty page reached with a cursor is a normal end of list
- Admins and moderators are interleaved through this roster at arbitrary positions, so do not derive a moderator list by filtering the first page. Use community/moderators
- Price: $0.0008/call

**Community Moderators**
- Endpoint: GET /twitter/community/moderators
- Page through a community's moderators and admins, in the same { user, role } row shape community/members returns, under the same members key so one type serves both and they cannot drift
- A SEPARATE upstream operation, not a filter over the member roster, and the difference is correctness rather than efficiency: filtering page one of that roster returns the moderators among the first 20 members while looking like a complete answer
- Admins are included, carrying role Admin, so read the role field rather than assuming every row is a Moderator. Same slice-and-bare-next_cursor paging contract as community/members
- Price: $0.0008/call

**Community About**
- Endpoint: GET /twitter/community/about
- The About tab for one community: its moderators, and a preview of its members, both as FULL user profiles with bio, follower and following counts, tweet count, location, website and join date. community/members and community/moderators return a reduced row instead, so this answers who runs a community in one call rather than one call plus a profile lookup per person
- Despite the name it carries NO community metadata: no description, no rules, no member_count, no join policy. Use community/info for those. It is not paginated, because the upstream operation is not, and the members preview is capped by X at 10 rows so it is a sample and not a roster
- moderators_truncated and members_truncated are read off X's own show-more marker rather than inferred from the row count
- Price: $0.0008/call

**Community Tweets**
- Endpoint: GET /twitter/community/tweets
- Page through a community's own post timeline as full tweet objects, with optional ranking_mode ordering
- The community's PINNED post comes back as its own pinned field and is NOT an item inside tweets: X delivers it under a separate timeline instruction and does not repeat it in the feed, so a client that iterates only tweets drops it silently. It is often the community's rules post. For one flat list, read pinned first, then tweets, with no duplicate
- ranking_mode is a real upstream parameter, not a local re-sort. Recency is the default and the only value confirmed against a live capture; Relevance is accepted but unconfirmed, so do not depend on it
- Price: $0.0008/call

**Community Memberships**
- Endpoint: GET /twitter/community/memberships
- The inverse relation: given a numeric user_id, list every community that account belongs to. It is the only endpoint in this family that starts from an account rather than from a community
- Takes a numeric user id, NOT a handle and NOT a community id. Resolving a handle here would add a second upstream call and a second billing event to a request you believe is one read, so resolve it with user/info first
- Each row is the FULL community object, the same shape community/info returns, so profiling an account's community footprint costs no follow-up call per community
- An empty list is a real answer here and returns 200, unlike the member and moderator rosters, which 404 on an empty first page
- Price: $0.0008/call

### Article Endpoints
X's long-form Articles feature. Every write below (create, update_title, update_content, publish, unpublish) requires a registered session for the acting account and acts as that account, exactly like tweet/create; article/get is the one exception, a public pooled read that needs no session. Prices differ per endpoint, see each entry below.

**Create Article**
- Endpoint: POST /twitter/article/create
- Start a new draft article. No request body required
- Price: $0.0016/call

**Update Article Title**
- Endpoint: POST /twitter/article/update_title
- Set or change a draft or published article's title. Body: id (required), title (required)
- Price: $0.0016/call

- Endpoint: GET /twitter/spaces/info
- Metadata and participant roster for one X Space, live or ended: title, state, host, topics, scheduled and actual start/end times, peak live listeners, replay views, and the admin/speaker/listener rosters. Query: id (required, the token in a x.com/i/spaces/<id> URL), with_listeners (optional, default true), with_replays (optional, default true). Note that X does not retain the listener roster after a Space ends, so listeners is empty for an ended Space while total_live_listeners and total_replay_watched still reflect the real audience. Returns metadata only, not the Space audio.
- Price: $0.0008/call

- Endpoint: POST /twitter/article/update_cover_media
- Attach an already-uploaded image as an article's cover. Upload the image with media/upload first and pass the media_id it returns; this endpoint attaches, it does not upload. Body: id (required), media_id (required), media_category (optional, defaults to DraftTweetImage)
- Price: $0.0016/call

**Update Article Content**
- Endpoint: POST /twitter/article/update_content
- Replace an article's body. Body: id (required), content_state (required, Draft.js JSON: { blocks: [...], entityMap: [...] }), sent in the JSON request body and passed through verbatim, not validated
- Price: $0.0016/call

**Publish Article**
- Endpoint: POST /twitter/article/publish
- Publish a draft article. Posts a real, public announcement tweet linking to the article, unlike the other article writes this is a public, user-visible action. Body: id (required), audience (optional, default "Everyone"), reply_control (optional, default "Everyone"), caption (optional, up to 256 characters)
- Price: $0.0016/call

**Unpublish Article**
- Endpoint: POST /twitter/article/unpublish
- Revert a published article back to Draft. The announcement tweet is left in place; use article/delete to remove it too. Body: id (required)
- Price: $0.0016/call

**Get Article**
- Endpoint: GET /twitter/article/get
- Public read of a published article via its announcement tweet id or status URL (id or url query param). No customer session required, same auth model as tweet/detail. Returns 404 if the tweet is gone, protected, or is not an article announcement
- Price: $0.0008/call

**List Articles**
- Endpoint: GET /twitter/article/list
- List your own articles, filtered by lifecycle (X exposes no combined view). Params: lifecycle (draft or published, default draft), count (1-100, default 20), cursor (optional)
- Price: $0.0008/call

**Delete Article**
- Endpoint: POST /twitter/article/delete
- Delete an article. A draft is hard-deleted directly; a published article is unpublished first, then its announcement tweet is deleted. Body: id (required), lifecycle (optional hint: draft or published), tweet_id (optional hint, for published articles)
- Price: $0.0008/call

### Grok Endpoints
X's own in-app Grok, exposed as a normal request and response. Both endpoints run as the CUSTOMER'S authenticated account rather than a shared pooled one, because Grok eligibility and Grok usage caps belong to the X account: served off a pool, the config would describe our account instead of yours. Neither endpoint stores anything: no conversation, no turn, no prompt text.

**Grok Chat**
- Endpoint: POST /twitter/grok/chat
- Ask Grok a question and get one complete JSON reply: the answer text, the web pages it cited (url, domain, title, snippet), the tool calls it made, and the ids you need to continue. Grok reads X in real time, and a bare tweet or status URL as the message returns a structured summary of that post. Body: message (the prompt) or messages (prior turns, oldest first, whose last entry must be a user turn), mode (auto, fast or expert, default auto), conversation_id (optional, omit it and one is opened for you), image_count (optional, 0 to 4, default 4)
- The reply is BUFFERED, not streamed: one JSON response, the same shape as every other endpoint here
- The endpoint is STATELESS: conversation_id and response_id come back on every reply, and you pass them plus the prior turns back to continue. Nothing is retained on our side
- citations accumulate across every search Grok runs in a single answer, not just the last one, and repeated urls are collapsed. Some entries carry a url and a snippet with no title
- model can differ from requested_model, because auto is resolved at X's end: asking for grok-4-auto can come back answered by grok-4
- A prompt over 20,000 characters or more than 100 prior turns is refused with a 400 before any upstream call, so an over-long request never spends a call
- A reply carrying no readable answer returns 422 and is not billed
- Price: $0.0040/call

**Grok Config**
- Endpoint: GET /twitter/grok/config
- Whether your account is eligible for Grok, X's own reasons when it is not, the default mode and model, the mode-to-model mapping grok/chat accepts (auto is grok-4-auto, fast is grok-3-latest, expert is grok-4), and every model option X offers the account. Takes no parameters
- Call this once before your first chat. An ineligible account is the difference between a useful answer and an upstream refusal nobody can interpret
- Price: free

### Account Endpoints

**Account Info**
- Endpoint: GET /account/me
- Credit balance, usage summary, account details
- Price: free

**Send Feedback**
- Endpoint: POST /feedback
- File a bug, an idea, or a capability we are missing, from inside the AI agent you already use. JSON body: type (bug, idea, missing_capability), title (1 to 120 chars), details (1 to 8000 chars, three labelled bullets: what happened, repro, evidence, optionally after a one-line goal summary; no quotes of the conversation), optional area, evidence (identifiers only, up to 4096 bytes) and client. Returns 201 with the feedback id. Served un-prefixed on the public host, like account/me.
- Price: free

**Feedback Status**
- Endpoint: GET /feedback/{id}
- Read back one report: type, title, area, status (new, triaged, shipped, declined), the team's reply or null, created_at and updated_at. 404 for any id that is not on your account.
- Price: free

**List Feedback**
- Endpoint: GET /feedback
- List the reports your account has filed, newest first. Query: limit (1 to 100, default 25), cursor, status (new, triaged, shipped, declined), type (bug, idea, missing_capability). Cursor paging, so a report filed between two calls cannot make a page skip or repeat a row. Each item carries the same fields as GET /feedback/{id} without details or evidence, so a list can never become a bulk export. An account that has filed nothing answers 200 with an empty array.
- Price: free

### Write Action Endpoints
The simple write actions below run at $0.0008 per call, the same rate as a read. Tweet creation and DM send are premium at $0.0016 per call. Write actions use a bring-your-own auth_token (and ct0) passed per request. Credentials are used in-flight to proxy the action to Twitter/X and are never stored.

**Favorite (Like)**
- Endpoint: POST /twitter/tweet/favorite
- Like a tweet on behalf of the authenticated account
- Price: $0.0008/call

**Unfavorite (Unlike)**
- Endpoint: POST /twitter/tweet/unfavorite
- Remove a like from a tweet
- Price: $0.0008/call

**Retweet**
- Endpoint: POST /twitter/tweet/retweet
- Repost a tweet
- Price: $0.0008/call

**Undo Retweet**
- Endpoint: POST /twitter/tweet/unretweet
- Remove a repost
- Price: $0.0008/call

**Bookmark**
- Endpoint: POST /twitter/tweet/bookmark
- Add a tweet to bookmarks
- Price: $0.0008/call

**Remove Bookmark**
- Endpoint: POST /twitter/tweet/unbookmark
- Remove a tweet from bookmarks
- Price: $0.0008/call

**Follow**
- Endpoint: POST /twitter/user/follow
- Follow an account
- Price: $0.0008/call

**Unfollow**
- Endpoint: POST /twitter/user/unfollow
- Unfollow an account
- Price: $0.0008/call

**Update Profile**
- Endpoint: POST /twitter/user/update_profile
- Change the display name, bio, location or link on your own account. A genuine PARTIAL update: fields you omit keep their current values rather than being blanked, so sending just a name will not wipe the bio
- An empty string CLEARS a field, and an omitted field is left alone: "" blanks the value, an absent key leaves it where it is
- At least one of name, description, location or url is required; a request carrying none is refused with 400
- Returns ok and updated_fields, which echoes the field names you SENT rather than a diff against your previous profile
- Price: $0.0016/call

**Update Avatar**
- Endpoint: POST /twitter/user/update_avatar
- Replace the profile picture on your own account. Send base64-encoded image bytes in the JSON request body as image; not a URL and not multipart (banner and data are accepted aliases)
- Takes effect immediately with NO UNDO, and X keeps no history: save profile_image_url from user/info first if you may want the old image back
- Every accepted upload mints a NEW media id, so profile_image_url changes even when you re-upload the identical image, which is how you confirm the write applied
- An image X cannot decode is refused upstream with an error rather than a 200 that applies nothing
- Price: $0.0016/call

**Update Banner**
- Endpoint: POST /twitter/user/update_banner
- Replace the wide header image on your own account. Send base64-encoded image bytes in the JSON request body as banner; not a URL and not multipart (image and data are accepted aliases)
- Takes effect immediately with NO UNDO, and X keeps no history: save cover_picture from user/info first if you may want the old image back
- Read the banner back with user/info specifically, as cover_picture. Several of X's own endpoints decline to report the field, so an empty answer from elsewhere is not evidence the account has no banner
- An image X cannot decode is refused upstream with an error rather than a 200 that applies nothing
- Price: $0.0016/call

**Create Tweet**
- Endpoint: POST /twitter/tweet/create
- Post a new tweet, reply, or quote-tweet; attach media_ids for images or video
- Price: $0.0016/call

**Delete Tweet**
- Endpoint: POST /twitter/tweet/delete
- Delete a tweet the authenticated account authored (irreversible)
- Price: $0.0008/call

**Create Draft Tweet**
- Endpoint: POST /twitter/draft/create
- Save a PRIVATE draft on your own account. Nothing is posted: the draft sits in X's own composer under Drafts until you publish or delete it. Takes text plus optional media_ids, reply_to and quote
- Requires text; a draft with no text is refused with 400
- Price: $0.0016/call

**Edit Draft Tweet**
- Endpoint: POST /twitter/draft/edit
- Replace an existing draft's contents by id. The fields you send become the draft in full rather than merging into it, so send everything it should keep
- Price: $0.0016/call

**Delete Draft Tweet**
- Endpoint: POST /twitter/draft/delete
- Delete a draft by id. A draft was never public, so this retracts nothing and notifies nobody
- Price: $0.0008/call

**List Draft Tweets** (read)
- Endpoint: GET /twitter/draft/list
- List your own drafts, newest first unless you pass ascending=true. Each row carries draft_tweet_id, text, and thread_truncated, true when the draft is a thread and the text is only its first tweet
- A partial flag is present and true only when the answer was read but not fully understood. It is ABSENT on a clean read, so an empty drafts array with no partial flag means you have no drafts rather than that we could not tell
- No cursor: one call returns the whole list. No created_at: X sends no timestamp on a draft row
- Price: $0.0016/call

**Schedule Tweet**
- Endpoint: POST /twitter/scheduled/create
- Schedule a tweet to post PUBLICLY at a future instant. Unlike a draft it will go out on its own unless cancelled first
- execute_at is epoch SECONDS and must be in the future. A millisecond value is refused with a message naming the unit, never silently scheduled tens of thousands of years out
- Price: $0.0016/call

**Cancel Scheduled Tweet**
- Endpoint: POST /twitter/scheduled/delete
- Cancel a pending scheduled post by id so it never sends. After it has published there is nothing left to cancel; delete the resulting tweet with tweet/delete instead
- Price: $0.0008/call

**List Scheduled Tweets** (read)
- Endpoint: GET /twitter/scheduled/list
- List your pending scheduled posts. Each row carries scheduled_tweet_id, text, thread_truncated, execute_at and X's own state label
- execute_at comes back in epoch SECONDS. X answers this operation in milliseconds and the value is normalised, so a timestamp read here can go straight back into scheduled/create
- Price: $0.0016/call

**Send DM**
- Endpoint: POST /twitter/dm/send
- Send a Direct Message to a user by their numeric recipient_id
- Price: $0.0016/call

**Upload Media**
- Endpoint: POST /twitter/media/upload
- Upload a base64 image and receive a media_id to attach to a tweet
- Price: $0.0008/call

**Media Status** (read)
- Endpoint: GET /twitter/media/status
- Check the async processing state of an uploaded media_id (pending, in_progress, succeeded, failed) before attaching it to a tweet; poll until succeeded, waiting check_after_secs between calls
- Price: $0.0008/call

**Revoke Session**
- Endpoint: GET /twitter/customer/session/status
- Read back the X session stored against your API key without changing it. Returns registered, the resolved username and twitter_user_id, status of ok or dead, created_at, updated_at, last_used_at, and an egress block giving source (session, sticky_residential, pool_residential or direct), customer_proxy_in_use, and a note. Never returns auth_token, ct0, or any proxy URL. The API key is read from the authenticated request, never from the body or the query string, so a key can only ever read its own session. Free, and it changes nothing

- Endpoint: POST /twitter/customer/session/delete
- Delete the auth_token and ct0 you registered with POST /twitter/customer/session. The API key is read from the authenticated request, never from the body or the query string, so a key can only ever revoke its own session
- Idempotent: returns 200 with deleted true when a stored session was removed and deleted false when there was nothing to remove, so calling it twice is not an error
- Deletes our stored copy only. It does not log the account out of x.com; to invalidate the cookies themselves, revoke the session in your X account settings as well
- Price: free. A customer who has run out of credits must still be able to delete their own credentials
- Takes no parameters

### Monitoring Endpoints

**Create Monitor**
- Endpoint: POST /twitter/monitor
- Watch an X account for new posts and get them pushed to your webhook(s), HMAC-signed, on a shared poll interval
- Price: free

**List Monitors**
- Endpoint: GET /twitter/monitor
- List every monitor on your account
- Price: free

**Update Monitor**
- Endpoint: POST /twitter/monitor/{id}
- Pause, resume, or change which webhooks a monitor delivers to. Resuming re-runs the same capacity and per-account cap checks as creating a new monitor
- Price: free

**Delete Monitor**
- Endpoint: DELETE /twitter/monitor/{id}
- Stop watching an account and remove the monitor (soft-deleted; delivery history is retained)
- Price: free

**Monitor Health**
- Endpoint: GET /twitter/monitor/{id}/health
- Check one monitor's poll status, degradation flag, and last-seen tweet id
- Price: free

**Account Monitor Health**
- Endpoint: GET /twitter/monitor/health
- Account-wide monitoring rollup in one call: service status, active/paused monitor counts, and 24h pending/delivered/failed delivery counts. No path parameter, never 404s.
- Price: free

**Monitor Deliveries**
- Endpoint: GET /twitter/monitor/deliveries
- Recent delivery events across every monitor, each with real detection and delivery latency measured from X's own post timestamp
- Price: free

**Compat: Add User to Tweet Monitoring**
- Endpoint: POST /oapi/x_user_stream/add_user_to_monitor_tweet
- x_user_stream-shaped drop-in for Create Monitor, for migrating an existing x_user_stream integration without rewriting it against /twitter/monitor
- Price: free

**Compat: Remove User from Tweet Monitoring**
- Endpoint: POST /oapi/x_user_stream/remove_user_to_monitor_tweet
- x_user_stream-shaped drop-in for Delete Monitor
- Price: free

**Compat: List Tweet-Monitored Users**
- Endpoint: GET /oapi/x_user_stream/get_user_to_monitor_tweet
- x_user_stream-shaped drop-in for List Monitors
- Price: free

**Create Webhook**
- Endpoint: POST /twitter/webhook
- Register a URL to receive monitor events. Returns the HMAC signing secret exactly once
- Price: free

**List Webhooks**
- Endpoint: GET /twitter/webhook
- List every webhook on your account (never returns the signing secret)
- Price: free

**Test Webhook**
- Endpoint: POST /twitter/webhook/{id}/test
- Fire one real signed test delivery right now and get the outcome synchronously, no polling required
- Price: free

**Replay Dead Deliveries**
- Endpoint: POST /twitter/webhook/{id}/redrive
- Re-queue deliveries that were dead-lettered while your endpoint was down, so they are sent again with a full retry budget; permanent failures (410 Gone, deleted webhook) are skipped rather than replayed
- Price: free

**Delete Webhook**
- Endpoint: DELETE /twitter/webhook/{id}
- Remove a webhook (soft-deleted; delivery history referencing it is retained)
- Price: free

## Authentication

All API requests require an API key passed in the `Authorization` header:
```
Authorization: Bearer YOUR_API_KEY
```

Base URL: https://api.twitterapis.com

## Getting Started

1. Sign up at https://www.twitterapis.com/signup (instant, no approval wait)
2. Receive your API key and $0.50 free credits
3. Make requests to https://api.twitterapis.com with `Authorization: Bearer YOUR_API_KEY` header
4. Read full docs at https://docs.twitterapis.com

## Use Cases

- Social media analytics and monitoring
- Brand sentiment analysis
- Influencer discovery and research
- Academic and social research
- Content aggregation
- Competitive intelligence
- Automated engagement tracking
- Market trend analysis

## Links

- Website: https://www.twitterapis.com
- API Documentation: https://docs.twitterapis.com
- Pricing: https://www.twitterapis.com/pricing
- Pricing Comparison: https://www.twitterapis.com/twitter-api-pricing
- API Alternatives: https://www.twitterapis.com/twitter-api-alternatives
- Rate Limits: https://www.twitterapis.com/twitter-api-rate-limits
- Cost Calculator: https://www.twitterapis.com/twitter-api-cost-calculator
- Free API Options: https://www.twitterapis.com/twitter-free-api
- Unofficial API Guide: https://www.twitterapis.com/twitter-unofficial-api
- Twitter User API: https://www.twitterapis.com/twitter-user-api
- Twitter List API: https://www.twitterapis.com/twitter-list-api
- Twitter Mentions API: https://www.twitterapis.com/twitter-mentions-api
- Twitter Timeline API: https://www.twitterapis.com/twitter-timeline-api
- Twitter API Key: https://www.twitterapis.com/twitter-api-key
- TwitterAPIs vs RapidAPI: https://www.twitterapis.com/twitterapis-vs-rapidapi
- TwitterAPIs vs Tweepy: https://www.twitterapis.com/twitterapis-vs-tweepy
- TwitterAPIs vs TweetAPI: https://www.twitterapis.com/twitterapis-vs-tweetapi
- TwitterAPIs vs TwexAPI: https://www.twitterapis.com/twitterapis-vs-twexapi
- Quickstart: https://www.twitterapis.com/quickstart
- Security: https://www.twitterapis.com/security
- Changelog: https://www.twitterapis.com/changelog
- Press and Listings: https://www.twitterapis.com/press
- Sign Up: https://www.twitterapis.com/signup
- Contact: https://www.twitterapis.com/contact