# TwitterAPIs

> The cheapest Twitter/X REST API. Search tweets and users, resolve a tweet into its full thread, read profiles and timelines, page the follower graph, and run write actions, all over plain HTTP with Bearer auth and JSON. Base URL: https://api.twitterapis.com/twitter. Pay per call, no OAuth dance.

## Docs

- [Overview](https://docs.twitterapis.com/docs): REST API for Twitter and X data. Search tweets and users, read profiles and timelines, walk the follower graph, and run write actions. Bearer auth, JSON.
- [Authentication](https://docs.twitterapis.com/docs/getting-started/authentication): TwitterAPIs uses a single bearer token on every request. No OAuth, no scopes, no token refresh.
- [Errors](https://docs.twitterapis.com/docs/getting-started/errors): HTTP status codes TwitterAPIs returns, the JSON error shape, and how to handle each one in your client.
- [MCP Server](https://docs.twitterapis.com/docs/getting-started/mcp): Connect the @twitterapis/mcp server to Claude, Cursor, and any Model Context Protocol client so your AI agent can search tweets and read profiles as native tools.
- [Pagination](https://docs.twitterapis.com/docs/getting-started/pagination): Cursor-based pagination across search, list, and follower-graph endpoints, with a copy-paste loop that reads every page.
- [Quickstart](https://docs.twitterapis.com/docs/getting-started/quickstart): Get an API key and make your first TwitterAPIs request in under two minutes, with copy-paste curl, JavaScript, and Python.
- [Rate Limits](https://docs.twitterapis.com/docs/getting-started/rate-limits): TwitterAPIs has no platform rate-limit caps. You pay per call, so spend is the only ceiling. Be a good client.
- [Client Libraries](https://docs.twitterapis.com/docs/getting-started/sdks): Copy-paste minimal TwitterAPIs clients for JavaScript and Python, built on the bearer-token pattern, with retries and cursor pagination handled for you.
- [Write Sessions](https://docs.twitterapis.com/docs/getting-started/write-sessions): Register your own X session once, or pass credentials per request. Covers proxy_url egress routing and exactly what is stored.
- [Build a Twitter/X brand monitor](https://docs.twitterapis.com/docs/guides/brand-monitor): Poll advanced_search on an interval, dedupe by tweet ID, and surface net-new mentions. Full cURL, Python, and Node samples with cost math.
- [Export an account's full follower list](https://docs.twitterapis.com/docs/guides/export-followers): Page through /twitter/user/followers_v2 with the cursor until exhausted, write results to CSV or JSON. Full cURL, Python, and Node samples with pagination, error handling, and cost math for a 100K-follower account.
- [Guides](https://docs.twitterapis.com/docs/guides): End-to-end recipes for common Twitter/X data tasks. Each guide ships working cURL, Python, and Node samples with cost math included.
- [Stream the latest tweets for a keyword](https://docs.twitterapis.com/docs/guides/keyword-stream): Use advanced_search with product=Latest and a high-water-mark tweet ID to poll new tweets in near real time. Full cURL, Python, and Node samples with cost math.
- [Wire TwitterAPIs into Claude, Cursor, and Windsurf](https://docs.twitterapis.com/docs/guides/mcp-integration): Install the TwitterAPIs MCP server in under two minutes and let your AI agent search tweets, fetch profiles, and read timelines without writing a line of glue code.
- [Post and delete tweets with a session](https://docs.twitterapis.com/docs/guides/posting-tweets): Register a customer session once with your X credentials, then create and delete tweets programmatically. Full cURL, Python, and Node samples with cost math.
- [Trim any response with fields and compact](https://docs.twitterapis.com/docs/guides/response-projection): Every GET endpoint accepts ?fields=a,b.c and ?compact=1 to return only the fields you name. Cuts a tweet page by 70 to 90 percent for LLM tool callers, with pagination and error envelopes always kept. cURL and Python samples plus the exact projection rules.
- [Sample apps](https://docs.twitterapis.com/docs/guides/sample-apps): Open-source projects built on the twitterapis.com API that you can run, read and copy from: the MCP server and a read-only Claude skill that audits an X account.
- [Account Info](https://docs.twitterapis.com/docs/reference/account/account-me): Returns the account behind your API key: remaining credits, credits consumed, total requests served, and when the account was created. Use it to show a balance in your own dashboard or to alert before you run out of credits. This call is free and is not metered. Cost: Free per call.
- [Payment History](https://docs.twitterapis.com/docs/reference/account/account-payments): Returns the payment history for the account behind your API key, ordered newest first. Each entry records what was paid, how many credits it added, and whether the payment completed. Use it to reconcile top-ups against your own billing records. This call is free. Cost: Free per call.
- [List Feedback](https://docs.twitterapis.com/docs/reference/account/feedback-get): Returns the calling account's own feedback reports, newest first, keyset-paginated on (created_at desc, id desc). Each item carries the same summary fields as GET feedback/{id} (id, type, title, area, status, response, created_at, updated_at) and never details or evidence, so paging this endpoint can never turn into a bulk export of a report's full body: read one by id to get that. Free, never metered, and shares the 10-per-minute limiter with POST feedback and GET feedback/{id}. Cost: Free per call.
- [Feedback Status](https://docs.twitterapis.com/docs/reference/account/feedback-id): Returns one feedback report filed from your account, by id: what was sent (type, title, area), its status (new, triaged, shipped or declined), the team's response text or null, and timestamps. updated_at moves only when status or response changes, so an agent can tell a report that has been looked at from one that has not. Free, never metered. Any id that is not on your account answers 404, including ids that are not UUIDs. Cost: Free per call.
- [Send Feedback](https://docs.twitterapis.com/docs/reference/account/feedback-post): Files a product feedback report against your account. It exists for AI agents (Claude Code, Cursor, any MCP client) working against this API: when a call fails, a capability is missing, or the user asks for it, the agent drafts a report locally, the user reviews it, and the client sends it here. The report reaches the team as a stored row plus a Slack post, and the returned id lets the agent read its status later. Free, never metered, rate limited to 10 per minute per key. Cost: Free per call.
- [Overview](https://docs.twitterapis.com/docs/reference/account): Account: Your API account: credit balance, usage totals, payment history, and product feedback filed from the tool you are using. Served from the API root (https://api.twitterapis.com/account/* and /feedback), not under /twitter, because billing owns their authentication. Free.
- [Create Article](https://docs.twitterapis.com/docs/reference/articles/article-create): Start a new draft Article as the account behind your registered session, and return its entity id, ready for Update Title / Update Content. The draft is empty until you call those. Requires a registered session. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Delete Article](https://docs.twitterapis.com/docs/reference/articles/article-delete): Delete an article you own, identified by its entity id. A Draft is hard-deleted directly. A Published article is unpublished first (reverting it to Draft) and then its announcement tweet is deleted, which is what makes it stop being publicly reachable, a two-step reversal for Publish Article. Pass lifecycle and tweet_id as optional fast-path hints when you already know them (from a prior list/create response); omitted, the server resolves them itself by scanning your Draft then Published lists, costing a couple of extra round trips. Requires a registered session. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Get Article](https://docs.twitterapis.com/docs/reference/articles/article-get): Read an article's full content. Two mutually exclusive forms: id or url (the announcement tweet id or status URL) for a public read that needs no session, works for Published articles only. Or article_id (the article's own entity id, from Article Create or Article List) for an owner-only read that requires a registered session and also works for your own Drafts. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [List Articles](https://docs.twitterapis.com/docs/reference/articles/article-list): List the caller's own articles at one lifecycle at a time: Draft or Published (default Draft). X exposes no combined view across both, so call it twice, once per lifecycle, to see everything. Cursor-paginated. Requires a registered session. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Publish Article](https://docs.twitterapis.com/docs/reference/articles/article-publish): Publish a draft article as the account behind your registered session, transitioning it from Draft to Published. WARNING: publishing posts a real, public announcement tweet on the account's timeline. This is not a preview or a private action, and it cannot be undone by re-editing the article: once published, the only way back is Delete Article, which unpublishes the article AND removes the announcement tweet. Requires a registered session. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Unpublish Article](https://docs.twitterapis.com/docs/reference/articles/article-unpublish): Revert a Published article back to Draft, identified by its entity id. The announcement tweet the original publish posted is left in place; use Delete Article to remove it too. X server-validates this transition and returns a 422 (invalid_lifecycle) if the article is not currently Published. Requires a registered session. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Update Article Content](https://docs.twitterapis.com/docs/reference/articles/article-update-content): Replace the body of an article you own with a new content_state, identified by its entity id. content_state is Draft.js editor-state JSON ({ blocks: [...], entityMap: [...] }) that you build client-side; in the shape the X Article editor produces. Blocks are forwarded with only key, text, type, data, entityRanges and inlineStyleRanges; X's schema rejects any other block field (depth included). Block types: unstyled, header-two, unordered-list-item, ordered-list-item, blockquote and atomic (a one-space block that carries an entity through entityRanges). entityMap is an ARRAY of { key, value: { type, mutability, data } }; entity data is snake_case on input and comes back camelCase: TWEET (an embedded post) { tweet_id }, MEDIA (an inline image) { caption, entity_key, media_items: [{ local_media_id, media_category: "DraftTweetImage", media_id }] } with media_id from media/upload, DIVIDER {}, LINK { url } over a text range, MARKDOWN { markdown } for tables. A field X does not know is refused with 422, reason validation_failed and the offending path in detail. Measured live 2026-09-18. Requires a registered session. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Update Article Cover Image](https://docs.twitterapis.com/docs/reference/articles/article-update-cover-media): Set the cover image on an article you own, identified by its entity id. This attaches media you have already uploaded; it does not upload anything itself, so call media/upload first and pass the media_id it returns. Requires a registered session. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Update Article Title](https://docs.twitterapis.com/docs/reference/articles/article-update-title): Set the title of an article you own, identified by its entity id. Requires a registered session. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Overview](https://docs.twitterapis.com/docs/reference/articles): Articles: Create, edit, publish, and read X's long-form Articles (X's internal name: Notes). Publishing posts a real announcement tweet; reading a published article is a public call that needs no session.
- [DM Conversation](https://docs.twitterapis.com/docs/reference/direct-messages/dm-conversation): Fetch the messages inside a single DM conversation. Pass a conversation_id from GET /dm/list. Each message carries its ID, sender ID, timestamp, and text. Authenticate with a registered session (POST /customer/session) or per-call x-auth-token and x-ct0 headers. Read-only: this does not send DMs. Cost: $0.0016 per call.
- [DM Inbox](https://docs.twitterapis.com/docs/reference/direct-messages/dm-list): List the DM conversations (inbox) for the account behind your session. Returns each conversation's ID, type, and participant user IDs. Pass a conversation_id to GET /dm/conversation to read its messages. Authenticate with a registered session (POST /customer/session) or per-call x-auth-token and x-ct0 headers, so one API key can poll the inboxes of many accounts. Read-only: this does not send DMs. It reads X's standard DM inbox, so conversations X has moved to end-to-end encrypted chat may not appear, and conversations still in the message-requests folder may be missing. Cost: $0.0016 per call.
- [Send DM](https://docs.twitterapis.com/docs/reference/direct-messages/dm-send): Send a direct message to a user as the authenticated account. Requires a logged-in session for the acting account. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Overview](https://docs.twitterapis.com/docs/reference/direct-messages): Direct Messages: Read your account's DM inbox and the message history of a single conversation, and send new messages, all acting as the account behind your registered session.
- [Community About](https://docs.twitterapis.com/docs/reference/communities/community-about): The About tab for one community: its moderators, and a preview of its members, both returned as FULL user profiles with bio, follower and following counts, tweet counts, location, website, banner and join date. Community Members and Community Moderators return a reduced row instead, so this is the endpoint that answers who runs a community in one call rather than one call plus a profile lookup per person. It is not paginated, because the upstream operation is not. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Community Info](https://docs.twitterapis.com/docs/reference/communities/community-info): Look up a single X Community by its numeric id and get back its name, description, member count, join policy, primary topic, posted rules and both banners. This endpoint returns the REDUCED form of the Community object: eight of its 24 fields come back empty here and are populated by Community Memberships instead, which the response table marks field by field. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Community Members](https://docs.twitterapis.com/docs/reference/communities/community-members): Fetch the member roster of an X Community, cursor-paginated, with each row carrying that member's own role in the community: Admin, Moderator or Member. Admins and moderators appear in this list alongside ordinary members and are not grouped, so do not derive a moderator list by filtering the first page. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Community Memberships](https://docs.twitterapis.com/docs/reference/communities/community-memberships): The inverse relation: given a numeric X user id, list the communities that account belongs to, cursor-paginated. Each row is the FULL community object, and it is the most populated form of it this API returns: admin, invites_policy, question, search_tags, members_facepile_ids and a real moderator_count all arrive here and do not on Community Info. Profiling an account's community footprint takes one call per page rather than a follow-up lookup per community. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Community Moderators](https://docs.twitterapis.com/docs/reference/communities/community-moderators): Fetch the moderators and admins of an X Community, cursor-paginated, in the same row shape Community Members returns. This is a separate upstream operation rather than a filter over the member roster, because moderators are interleaved through that roster at arbitrary positions. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Community Search](https://docs.twitterapis.com/docs/reference/communities/community-search): Find communities by keyword, cursor-paginated. This is the discovery step the rest of this 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, nsfw flag, topic name, banners and the facepile avatars, which is exactly what X's search operation sends and nothing more. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Community Tweets](https://docs.twitterapis.com/docs/reference/communities/community-tweets): Fetch the post timeline of an X Community, cursor-paginated as full tweet objects, with optional ordering control. The community's pinned post is returned as its own field rather than mixed into the feed, because X delivers it under a different timeline instruction and does not repeat it in the feed. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Overview](https://docs.twitterapis.com/docs/reference/communities): Communities: Read an X Community: its metadata and rules, its member and moderator rosters, its own post timeline including the pinned post, and the inverse relation, every community a given account belongs to. These are public reads that do not run as your account, so the four fields that describe the CALLER's own relationship to a community (role, can_join, is_pinned, viewer_relationship_type) always come back null.
- [Overview](https://docs.twitterapis.com/docs/reference/follower-graph): Follower Graph: Page through followers and following lists, including the verified-only and v2 cursor-paginated variants.
- [User Followers (v2)](https://docs.twitterapis.com/docs/reference/follower-graph/user-followers-v2): The v2 variant of the followers endpoint. Same data, with a more consistent cursor model and additional user fields. Prefer v2 for new integrations. Cost: $0.0008 per call.
- [Followers You Know](https://docs.twitterapis.com/docs/reference/follower-graph/user-followers-you-know): Return the followers of the account named by user_id that the account behind your registered session also follows: the mutual-connection overlap from your perspective. Returns full user objects, cursor-paginated. Requires a registered session and a numeric user_id. Cost: $0.0008 per call.
- [User Followers](https://docs.twitterapis.com/docs/reference/follower-graph/user-followers): Fetch a user's followers, cursor-paginated. Returns full user objects. For large accounts, page with next_cursor until the users array comes back empty (the follower graph keeps returning a non-null cursor even on the final page). Cost: $0.0008 per call.
- [User Following (v2)](https://docs.twitterapis.com/docs/reference/follower-graph/user-following-v2): The v2 variant of the following endpoint. Same data as the v1 following call, with a more consistent cursor model and additional user fields. Prefer v2 for new integrations. Cost: $0.0008 per call.
- [User Following](https://docs.twitterapis.com/docs/reference/follower-graph/user-following): Fetch the accounts a user follows, cursor-paginated. Returns full user objects. Page with next_cursor until the users array comes back empty (the follower graph keeps returning a non-null cursor even on the final page). Cost: $0.0008 per call.
- [Verified Followers](https://docs.twitterapis.com/docs/reference/follower-graph/user-verified-followers): Fetch only the Verified (Blue) accounts that follow a user, cursor-paginated. A fast way to filter a large follower base down to higher-signal accounts. Cost: $0.0008 per call.
- [Revoke Session](https://docs.twitterapis.com/docs/reference/account-session/customer-session-delete): Delete the X session cookies stored against your API key. The key is taken from the authenticated request, and the handler reads no identity from the body, the query string, or any second header, so a call can only ever remove the caller's own stored session. It is idempotent and answers 200 whether or not a row was there to remove. This call is free. Cost: Free per call.
- [Session Status](https://docs.twitterapis.com/docs/reference/account-session/customer-session-status): Read the X session stored against your API key without changing it. Returns the account the session actually resolved to, whether it is still live or has been marked dead, when it was registered and last used, and which egress tier a write would leave on. It never returns auth_token, ct0, or any proxy URL. The key is taken from the authenticated request and the handler reads no identity from the body, the query string, or any second header, so a call can only ever read the caller's own session. This call is free. Cost: Free per call.
- [Register Session](https://docs.twitterapis.com/docs/reference/account-session/customer-session): Register your X session cookies so write actions (like, retweet, bookmark, follow, create or delete a tweet) and private-data reads (home timeline, bookmarks, likes, DMs, followers-you-know) run as your account. Supply auth_token and ct0 once; the session is stored against your API key and applied automatically. This call is free. Cost: Free per call.
- [Overview](https://docs.twitterapis.com/docs/reference/account-session): Account Session: Bring your own X session cookies (recommended), or mint a session from a username and password, so write actions and private-data reads act as your account. Free.
- [User Login](https://docs.twitterapis.com/docs/reference/account-session/user-user-login): Log in to an X account with a username and password (plus a TOTP secret when two-factor authentication is enabled). The API runs the login itself and stores the resulting session server-side against your API key; authenticated-account reads and the write tools then act as that account. It does NOT return session cookies: the response is {ok, username, message}, never auth_token/ct0/twid. Bringing your own auth_token and ct0 via POST /customer/session stays the primary, recommended path, since it never sends a password over the wire. This call costs $0.01, billed only on a successful login; a rejected attempt (bad credentials, captcha, etc.) is never charged. Cost: $0.0100 per call.
- [Grok Chat](https://docs.twitterapis.com/docs/reference/grok/grok-chat): Send a prompt to X's in-app Grok as the account behind your session and get back one complete JSON document: the answer text, the web pages Grok cited while writing it, and the searches it ran to find them. Grok reads X in real time, so it answers about posts and accounts a general-purpose model has never seen. Send a bare post URL as the message and you get a structured summary of that post instead, including what Grok reads out of its attached images. Billed at $0.0040 per answer. Cost: $0.0040 per call.
- [Grok Config](https://docs.twitterapis.com/docs/reference/grok/grok-config): Read the Grok settings for the account behind your session: whether X has enabled Grok for it, the reasons if not, and the model options it is allowed to choose between. Grok eligibility belongs to the X account rather than to us, so this runs as your own session. Call it once before your first chat request. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Overview](https://docs.twitterapis.com/docs/reference/grok): Grok: Ask X's own in-app Grok a question and get the answer back with the pages it cited. Grok reads X in real time, so it answers about posts and accounts a general model has never seen. Runs as your account, returns one buffered JSON document rather than a stream, and stores nothing: you pass prior turns back yourself.
- [Overview](https://docs.twitterapis.com/docs/reference/list-data): List Data: Read the members of any public Twitter/X List.
- [List Followers](https://docs.twitterapis.com/docs/reference/list-data/list-followers): Fetch a public List's followers by its numeric ID, cursor-paginated. Followers and members are different sets of people: members are the accounts the List owner added to it, followers are the accounts that subscribed to read it. A List with hundreds of members commonly has only a handful of followers, so a small count here is normal and is not a truncated page. next_cursor is null once X marks the roster complete. Cost: $0.0008 per call.
- [List Members](https://docs.twitterapis.com/docs/reference/list-data/list-members): Fetch the members of a public List by its numeric ID, cursor-paginated. Returns full user objects for every account in the List. Cost: $0.0008 per call.
- [List Timeline](https://docs.twitterapis.com/docs/reference/list-data/list-timeline): Fetch a public List's feed as X itself serves it, using the native List timeline. Includes members' retweets and X's own ordering. Paged only, with no date or reply filters. Cost: $0.0008 per call.
- [List Tweets](https://docs.twitterapis.com/docs/reference/list-data/list-tweets): Fetch posts written by the members of a public List through X's search index. Supports since and until date bounds and an include_replies toggle. Does not include retweets. Cost: $0.0008 per call.
- [Commentary Video Creators](https://docs.twitterapis.com/docs/reference/search/creator-commentary-video): Search X for native-video posts about a topic and get back the creators behind them, ranked. Each call reads one search page, keeps posts that carry native video, drops retweets, applies your min_views bar and groups what is left by author, with every exclusion counted by reason. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Overview](https://docs.twitterapis.com/docs/reference/search): Search: Full-text and structured search across tweets and users. Filter by query operators, author, date, language, and engagement.
- [Advanced Tweet Search](https://docs.twitterapis.com/docs/reference/search/tweet-advanced-search): Run a full-text tweet search using the same operator syntax as Twitter/X advanced search. Combine free text with operators such as from:, to:, since:, until:, min_faves:, and lang: to filter precisely. Results are cursor-paginated at roughly 20 tweets per call. Cost: $0.0008 per call.
- [User Search](https://docs.twitterapis.com/docs/reference/search/user-search): Search X's People directory by keyword. Matches against display name and handle; bio text is not searched, so a term that appears only in a bio returns no match. Useful for discovery, lead lists, and resolving partial handles into full profiles. Cost: $0.0008 per call.
- [Overview](https://docs.twitterapis.com/docs/reference/monitoring): Monitoring: Watch an X account for new posts and get them pushed to your own webhook, HMAC-signed, retried for 21 minutes on failure. Polls on a shared interval and never spends your read credits: monitor and webhook management are free account administration, not metered reads.
- [Monitor Deliveries](https://docs.twitterapis.com/docs/reference/monitoring/monitor-deliveries): Returns your most recent monitor delivery events, most recent first, each carrying the actual measured lag: detected_lag_ms is X's own post timestamp subtracted from the moment our scheduler enqueued the delivery (i.e. real detection latency, bound by the current poll interval), and delivery_lag_ms is the separate queue-to-webhook-POST time. Either can be null for an older event whose payload predates this field. Cost: Free per call.
- [List Monitors](https://docs.twitterapis.com/docs/reference/monitoring/monitor-get): Returns every non-deleted monitor on your account, most recently created first. Each entry includes its id, subject, status, and delivery configuration, so you can enumerate what already exists before creating, updating, or deleting a specific monitor. Cost: Free per call.
- [Account Monitor Health](https://docs.twitterapis.com/docs/reference/monitoring/monitor-health): Returns a single-call summary of your entire monitoring setup: overall status, how many of your monitors are active vs paused, and how many delivery attempts in the last 24 hours were pending, delivered, or failed. Distinct from Monitor Health above, which reports one monitor's cursor state, not your whole account's. Cost: Free per call.
- [Delete Monitor](https://docs.twitterapis.com/docs/reference/monitoring/monitor-id-delete): Soft-deletes the monitor: it stops polling immediately and disappears from List Monitors, but its delivery history is retained rather than cascade-deleted. Cost: Free per call.
- [Monitor Health](https://docs.twitterapis.com/docs/reference/monitoring/monitor-id-health): Returns a single monitor's current status, degradation flag, and cursor position, for building your own health dashboard. Cost: Free per call.
- [Update Monitor](https://docs.twitterapis.com/docs/reference/monitoring/monitor-id-post): Partial update of an existing monitor. Send status to pause or resume it, webhook_ids to change which webhooks receive its events, or both in the same call (applied atomically). Resuming a paused monitor re-runs the same capacity and per-account cap checks as creating a new one, since it adds load back to monitoring capacity. Cost: Free per call.
- [Create Monitor](https://docs.twitterapis.com/docs/reference/monitoring/monitor-post): Start watching an X account. Every new post from that account is delivered, HMAC-signed, to your registered webhook(s) on a shared poll interval. Free: monitor creation is account administration, not a metered read. Cost: Free per call.
- [Compat: Add User to Tweet Monitoring](https://docs.twitterapis.com/docs/reference/monitoring/oapi-x-user-stream-add-user-to-monitor-tweet): An x_user_stream-shaped request/response envelope, translated onto the exact same underlying monitor system as POST /twitter/monitor -- not a second capability, one system with two request shapes in front of it. Migrating an integration already built against that shape? Point it at this path instead of rewriting it against /twitter/monitor. Free: account administration, not a metered read, billed identically to /twitter/monitor. Cost: Free per call.
- [Compat: List Tweet-Monitored Users](https://docs.twitterapis.com/docs/reference/monitoring/oapi-x-user-stream-get-user-to-monitor-tweet): An x_user_stream-shaped response envelope for listing monitored users, backed by the same monitor rows GET /twitter/monitor returns. Honest field mapping, not fabricated: our monitors table stores no numeric Twitter user id and no separate display name, so x_user_id is always null and x_user_name/x_user_screen_name both carry the handle we actually store. is_monitor_profile (profile-change monitoring) is not a capability this API has -- always 0, never reported as on. Cost: Free per call.
- [Compat: Remove User from Tweet Monitoring](https://docs.twitterapis.com/docs/reference/monitoring/oapi-x-user-stream-remove-user-to-monitor-tweet): An x_user_stream-shaped request/response envelope for removing a monitored user, translated onto DELETE /twitter/monitor/{id}. id_for_user is exactly our monitor id -- get it from get_user_to_monitor_tweet, i.e. it is an opaque handle from that list response, which is what our id already is. Cost: Free per call.
- [Webhook Delivery Payload](https://docs.twitterapis.com/docs/reference/monitoring/webhook-delivery-payload): The exact JSON body a monitor POSTs to your webhook when a watched account posts, the signature headers that come with it, and how media (photos, video, animated GIFs) is represented.
- [List Webhooks](https://docs.twitterapis.com/docs/reference/monitoring/webhook-get): Returns every non-deleted webhook on your account. Never returns the signing secret; that is shown once, at creation. Cost: Free per call.
- [Replay Dead Deliveries](https://docs.twitterapis.com/docs/reference/monitoring/webhook-id-redrive): Re-queues this webhook's dead-lettered deliveries so the normal delivery loop sends them again, signed exactly like a live event and with a full retry budget. A delivery is dead-lettered after it fails all 8 attempts over 21 minutes, which is what happens when your endpoint is down longer than that window; until you call this, it is never sent again. Deliveries that died for a permanent reason (a 410 Gone, or a webhook you deleted) are deliberately not replayed, because they would fail identically, and are reported as skipped_permanent instead. Cost: Free per call.
- [Test Webhook](https://docs.twitterapis.com/docs/reference/monitoring/webhook-id-test): Sends a single HMAC-signed test event to this webhook's URL right now and returns the outcome synchronously. Unlike a real monitor event, a test send is never queued, retried, or dead-lettered: it is a one-shot diagnostic so you can confirm your endpoint and signature verification both work before relying on the webhook. Cost: Free per call.
- [Delete Webhook](https://docs.twitterapis.com/docs/reference/monitoring/webhook-id): Soft-deletes the webhook: it stops receiving deliveries immediately and disappears from List Webhooks, but delivery history referencing it is retained rather than cascade-deleted. Cost: Free per call.
- [Create Webhook](https://docs.twitterapis.com/docs/reference/monitoring/webhook-post): Register your HTTPS endpoint to receive signed monitor events. The signing secret is returned exactly once in this response; store it immediately, it cannot be retrieved again. Cost: Free per call.
- [Overview](https://docs.twitterapis.com/docs/reference/spaces): Spaces: Read an X Space by id: title, host, speakers, topics, timing and audience counts, for a Space that is scheduled, running or already ended.
- [Space Info](https://docs.twitterapis.com/docs/reference/spaces/spaces-info): Look up a single X Space by its id and get back its title, lifecycle state, host, topics, timing, audience counts and its admin, speaker and listener roster. Works for a Space that is scheduled, running or already ended. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Overview](https://docs.twitterapis.com/docs/reference/trends): Trends: Read what is trending on Twitter/X right now, worldwide, for a single country, for one X Explore tab or for the trends X labels Business and finance, plus the full set of locations trends are available for.
- [Trend Locations](https://docs.twitterapis.com/docs/reference/trends/trends-locations): Fetch the full set of locations X serves trends for, each with the WOEID to pass back to the Trends endpoint. Takes no parameters and returns the complete list. Cost: $0.0008 per call.
- [Trends](https://docs.twitterapis.com/docs/reference/trends/trends): Fetch the current top trends for one location. Ask for it by country name, ISO code, or numeric WOEID; with no location parameter you get Worldwide. X returns roughly 50 trends per location, ranked. Pass category instead: trending, news, sports, entertainment or for_you reads that X Explore tab, and business_and_finance keeps only the ranked trends X labels Business and finance on its Trending and News tabs. Cost: $0.0008 per call.
- [Overview](https://docs.twitterapis.com/docs/reference/tweet-details): Tweet Details: Resolve a single tweet into its full object: replies, retweeters, and the complete conversation thread.
- [Tweet Detail](https://docs.twitterapis.com/docs/reference/tweet-details/tweet-detail): Resolve a tweet ID into its complete object, including author, engagement counts, attached media, and any quoted tweet. The starting point for any single-tweet workflow. Cost: $0.0008 per call.
- [Tweet Quotes](https://docs.twitterapis.com/docs/reference/tweet-details/tweet-quotes): Fetch the quote tweets of a given tweet, cursor-paginated as full tweet objects, so you can read the commentary people attached rather than just count it. This endpoint is search-backed rather than served by a dedicated X operation, and every response says so in-band via source, search_query and quote_matched. Cost: $0.0008 per call.
- [Tweet Replies (Complete)](https://docs.twitterapis.com/docs/reference/tweet-details/tweet-replies-complete): Fetch all direct replies to a tweet in a single call. The endpoint walks the reply pages for you and returns them together, instead of one cursor page at a time, and reports whether it reached the end. Each call is bounded by max and a server-side time budget, so a large conversation can come back incomplete with a cursor to resume from. Cost: $0.0024 per call.
- [Tweet Replies](https://docs.twitterapis.com/docs/reference/tweet-details/tweet-replies): Fetch the direct replies to a given tweet, cursor-paginated. Combine with Tweet Detail to reconstruct a discussion or measure reply sentiment. Cost: $0.0008 per call.
- [Tweet Retweeters](https://docs.twitterapis.com/docs/reference/tweet-details/tweet-retweeters): Fetch the users who retweeted a given tweet, cursor-paginated. Useful for amplification analysis and identifying the accounts that spread a post. Cost: $0.0008 per call.
- [Tweet Thread](https://docs.twitterapis.com/docs/reference/tweet-details/tweet-thread): Given the first tweet of a thread, return the ordered list of tweets that make up the author's connected thread. The endpoint reads forward from the tweet you pass and does not walk backwards, so pass the thread's first tweet, which is the conversation_id carried on every tweet in that thread. Passing a later tweet returns only the tail of the thread. Cost: $0.0040 per call.
- [Overview](https://docs.twitterapis.com/docs/reference/user-reads): User Reads: Read a profile, its timeline, media, mentions, affiliates, and follow relationships by username or numeric ID.
- [User Affiliates](https://docs.twitterapis.com/docs/reference/user-reads/user-affiliates): Return the affiliated accounts linked under an organization's Verified Organizations profile. Useful for mapping a company to its employees and brand accounts. Cost: $0.0008 per call.
- [Audience Summary](https://docs.twitterapis.com/docs/reference/user-reads/user-audience-summary): Sample up to 100 of an account's followers, or of a tweet's retweeters, read each sampled account's About object, and return a country histogram of account_based_in with each country's share of the accounts whose country is known. The response also counts how many sampled accounts show each of seven documented profile signals and how many show three or more (likely_bot_count), a heuristic over profile fields rather than a verdict on any account. Cost: $0.0008 per billed item.
- [Blocked Accounts](https://docs.twitterapis.com/docs/reference/user-reads/user-blocking): Return the accounts blocked by the account behind your registered session, as full user objects, cursor-paginated. This reads your OWN block list. There is no user_id parameter because X exposes no way to read another account's blocks, so the endpoint does not pretend to offer one. Requires a registered session or per-call inline credentials. Cost: $0.0008 per call.
- [Bookmark Folder Timeline](https://docs.twitterapis.com/docs/reference/user-reads/user-bookmark-folder-timeline): Fetch the tweets inside one of the caller's own bookmark folders, identified by folder_id (from Bookmark Folders). Cursor-paginated. Requires a registered session. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Bookmark Folders](https://docs.twitterapis.com/docs/reference/user-reads/user-bookmark-folders): Fetch the caller's own bookmark folders. Each item carries the folder's id, name, and a cover image X auto-picks from its contents. Requires a registered session. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Bookmark Search](https://docs.twitterapis.com/docs/reference/user-reads/user-bookmark-search): Search the bookmarks of the account behind your registered session by keyword. Matches against bookmarked tweet text and returns full tweet objects. Cursor-paginated. Requires a registered session. Cost: $0.0008 per call.
- [Bookmarks](https://docs.twitterapis.com/docs/reference/user-reads/user-bookmarks): Fetch the bookmarked tweets for the account behind your registered session, newest first. Each item is a full tweet object with author and engagement counts. Cursor-paginated. Requires a registered session. Cost: $0.0008 per call.
- [Check Follow Relationship Batch](https://docs.twitterapis.com/docs/reference/user-reads/user-check-follow-relationship-batch): Check the directional relationship between one fixed account and up to 100 others in one request: one source against up to 100 targets, or one target against up to 100 sources. Each item carries the same relationship object GET /user/check_follow_relationship returns, read from the source's side: whether the source follows the target (following) and the target follows the source (followed_by), plus block, mute, and DM-eligibility flags. Results come back in request order, each with its relationship object or an error code. Cost: $0.0008 per billed item.
- [Check Follow Relationship](https://docs.twitterapis.com/docs/reference/user-reads/user-check-follow-relationship): Return the directional relationship between a source and target user: whether source follows target (following) and target follows source (followed_by), plus block, mute, and DM-eligibility flags. An account that does not exist returns a 404 with error not_found; the relationship object is null when X returns none. Cost: $0.0008 per call.
- [Home Timeline](https://docs.twitterapis.com/docs/reference/user-reads/user-home-timeline): Read the home timeline for the account behind your registered session: the ranked feed shown when that account opens X, most recent first. Returns full tweet objects with author and engagement counts. Cursor-paginated. Requires a registered session. Cost: $0.0008 per call.
- [User Info by ID](https://docs.twitterapis.com/docs/reference/user-reads/user-info-by-id): Resolve a numeric user ID into the full user object. Use this when you already have the stable ID (handles can change, IDs do not). Cost: $0.0008 per call.
- [User Info by Username](https://docs.twitterapis.com/docs/reference/user-reads/user-info): Resolve a username into the full user object: bio, follower and following counts, verification status, location, and avatar. The canonical entry point for profile lookups. Cost: $0.0008 per call.
- [User Likes](https://docs.twitterapis.com/docs/reference/user-reads/user-likes): Read the Likes tab of the account named by user_id, read through your registered session, most recent first. Returns full tweet objects, cursor-paginated. Returns an empty list when the account hides its likes. Requires a registered session and a numeric user_id. Cost: $0.0008 per call.
- [User Media](https://docs.twitterapis.com/docs/reference/user-reads/user-media): Fetch the media tweets posted by a user, cursor-paginated. Returns the tweet objects from the account's Media tab, with media URLs included under extended_entities.media. The tab occasionally surfaces a link-or-card tweet with no attachment, so guard on extended_entities before reading it. Cost: $0.0008 per call.
- [User Mentions](https://docs.twitterapis.com/docs/reference/user-reads/user-mentions): Return the tweets that mention a given account, cursor-paginated. This is the canonical way to read a handle's mentions; it is a thin wrapper over a to:username search and returns the same tweet objects. Cost: $0.0008 per call.
- [Muted Accounts](https://docs.twitterapis.com/docs/reference/user-reads/user-muting): Return the accounts muted by the account behind your registered session, as full user objects, cursor-paginated. Muting hides someone's posts from your timeline without blocking them, so this list is distinct from GET /user/blocking. This reads your OWN mute list; X exposes no way to read another account's, so there is no user_id parameter. Requires a registered session or per-call inline credentials. Cost: $0.0008 per call.
- [User Status](https://docs.twitterapis.com/docs/reference/user-reads/user-status): Return the liveness state of a handle: alive, suspended, not_found, or unavailable. Every outcome is an HTTP 200 and the caller branches on the status field. This exists because a standard profile lookup collapses suspended, deleted, and never-existed into one indistinguishable 404. Cost: $0.0008 per call.
- [User Tweets and Replies](https://docs.twitterapis.com/docs/reference/user-reads/user-tweets-and-replies): Page through a user's public timeline including the replies the account posted. This endpoint resolves to the same upstream timeline as GET /user/tweets and returns the same tweets in the same order, so treat it as an alias kept for compatibility rather than a wider result set. Each tweet carries is_retweet and is_reply for client-side filtering. Cost: $0.0008 per call.
- [Full Tweet History](https://docs.twitterapis.com/docs/reference/user-reads/user-tweets-complete): Collect a user's tweet history in bulk, auto-paginating server-side across upstream pages. Unlike GET /user/tweets (one upstream page per call), this drives pagination for you and returns a large batch in one request. Each call is bounded by both `max` and a server-side time budget, so it always returns inside a normal client timeout. When more history remains the response carries a `next_cursor` — pass it back as `cursor` to continue, and repeat until `next_cursor` is null. A public read: no registered session required. Cost: $0.0024 per call.
- [User Tweets](https://docs.twitterapis.com/docs/reference/user-reads/user-tweets): Page through a user's public timeline, cursor-paginated at roughly 20 tweets per call. The page mirrors the account's timeline as X returns it, so it contains original tweets, retweets, and the account's own replies. Each tweet carries is_retweet and is_reply, so filter client-side if you want original posts only. Cost: $0.0008 per call.
- [User About Batch](https://docs.twitterapis.com/docs/reference/user-reads/user-user-about-batch): Read the full About object for up to 100 accounts in one request: the same object GET /user/user_about returns, including X's "About this account" transparency panel (account country, how the account was created, and username-change history). Results come back in request order, each with its about object or an error code. Cost: $0.0008 per billed item.
- [User About](https://docs.twitterapis.com/docs/reference/user-reads/user-user-about): Read a profile's full About object: identity, bio, location, linked website, avatar, verification and identity-verification flags, professional account type and categories, follower and following counts, the account creation date, and X's "About this account" transparency panel (account country, how the account was created, and username-change history). Cost: $0.0008 per call.
- [Join Community](https://docs.twitterapis.com/docs/reference/write-actions/community-join): Add your X account to an open X Community by its numeric id. The call runs as your registered X session, sends one join request and reports what X answered, without reading the community first. Approval-gated communities are refused with a 409 and nothing is submitted. Billed at $0.0008 per applied write. Cost: $0.0008 per call.
- [Leave Community](https://docs.twitterapis.com/docs/reference/write-actions/community-leave): Remove your X account from a community it belongs to, by the community's numeric id. The call runs as your registered X session, sends one leave request and reports what X answered, without reading the community first. Billed at $0.0008 per applied write; a leave that does not apply is free. Cost: $0.0008 per call.
- [Create Draft Tweet](https://docs.twitterapis.com/docs/reference/write-actions/draft-create): Save a draft tweet on the account behind your registered session. A draft is private to that account and is never published: it appears in X's own composer under Drafts until you post or delete it. Accepts text, up to 4 media_ids, a reply_to and a quote, exactly like tweet/create. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Delete Draft Tweet](https://docs.twitterapis.com/docs/reference/write-actions/draft-delete): Delete a draft owned by the account behind your registered session, identified by its id. The draft is removed from X's composer. Nothing was ever public, so this publishes nothing and retracts nothing. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.
- [Edit Draft Tweet](https://docs.twitterapis.com/docs/reference/write-actions/draft-edit): Replace an existing draft's contents on the account behind your registered session. The fields you send become the draft in full: text is required, and media_ids, reply_to and quote are re-applied rather than merged, so send everything the draft should keep. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [List Draft Tweets](https://docs.twitterapis.com/docs/reference/write-actions/draft-list): List every draft on the account behind your registered session. Each row carries the draft id, its text, and thread_truncated, which is true when the draft is a thread and the text you get is only its first tweet. Ordering is X's: pass ascending=true to ask for the oldest first, omit it for X's default. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Overview](https://docs.twitterapis.com/docs/reference/write-actions): Write Actions: Act on behalf of an authenticated account: post, delete, like, retweet, bookmark and follow, each with its undo, plus the compose surface (private drafts and scheduled posts). MOST of these bill at $0.0008 per call, the same as a standard read, but not all: tweet/create, draft/create, draft/edit, draft/list, scheduled/create and scheduled/list are $0.0016. Read the price on the endpoint, never off this line.
- [Add List Member](https://docs.twitterapis.com/docs/reference/write-actions/list-add-member): Add an account to a List owned by your registered X session. Returns the List's member_count as proof the membership change landed. Cost: $0.0008 per call.
- [Create List](https://docs.twitterapis.com/docs/reference/write-actions/list-create): Create a List owned by your registered X session, with a name and an optional description and privacy flag. Populate it afterwards with Add List Member. Cost: $0.0016 per call.
- [Remove List Member](https://docs.twitterapis.com/docs/reference/write-actions/list-remove-member): Remove an account from a List owned by your registered X session. Returns the List's member_count as proof the membership change landed. Cost: $0.0008 per call.
- [Media Status](https://docs.twitterapis.com/docs/reference/write-actions/media-status): Return the async processing state of a media_id from Upload Media, so a caller can verify readiness before attaching a video, GIF, or large-media id to a tweet. Runs as your own logged-in account. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Upload Media](https://docs.twitterapis.com/docs/reference/write-actions/media-upload): Upload a base64-encoded image as the authenticated account and receive a media_id you can attach when creating a tweet. Runs as your own logged-in account. Billed at $0.0008 per call. Cost: $0.0008 per call.
- [Schedule Tweet](https://docs.twitterapis.com/docs/reference/write-actions/scheduled-create): Schedule a tweet from the account behind your registered session for a future instant. Unlike a draft, this WILL post publicly at execute_at unless you delete it first. execute_at is epoch SECONDS and must be in the future; a millisecond value is refused by name rather than scheduled tens of thousands of years out. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Cancel Scheduled Tweet](https://docs.twitterapis.com/docs/reference/write-actions/scheduled-delete): Cancel a scheduled tweet on the account behind your registered session, identified by its id, so it never posts. Do this before execute_at: once the post has gone out it is an ordinary tweet and tweet/delete is what removes it. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.
- [List Scheduled Tweets](https://docs.twitterapis.com/docs/reference/write-actions/scheduled-list): List every pending scheduled post on the account behind your registered session. Each row carries the id, its text, its execute_at in epoch SECONDS, X's own state label, and thread_truncated for a thread whose text is only its first tweet. Ordering is X's: pass ascending=true to ask for the oldest first. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Bookmark Tweet](https://docs.twitterapis.com/docs/reference/write-actions/tweet-bookmark): Bookmark a tweet as the authenticated account. Requires a logged-in session for the acting account. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.
- [Create Tweet](https://docs.twitterapis.com/docs/reference/write-actions/tweet-create): Post a new tweet as the account behind your registered session. Supports plain text, up to 4 image media_ids (from a prior media/upload), a reply (reply_to), and a quote (quote). Requires a registered session. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Delete Tweet](https://docs.twitterapis.com/docs/reference/write-actions/tweet-delete): Delete a tweet owned by the account behind your registered session. Identify it by id or url (read from the query string). Requires a registered session. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.
- [Like Tweet](https://docs.twitterapis.com/docs/reference/write-actions/tweet-favorite): Like a tweet as the authenticated account. Requires a logged-in session for the acting account. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.
- [Retweet](https://docs.twitterapis.com/docs/reference/write-actions/tweet-retweet): Retweet a tweet as the authenticated account. Requires a logged-in session for the acting account. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.
- [Remove Bookmark](https://docs.twitterapis.com/docs/reference/write-actions/tweet-unbookmark): Remove a previously saved bookmark as the authenticated account. Requires a logged-in session. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.
- [Unlike Tweet](https://docs.twitterapis.com/docs/reference/write-actions/tweet-unfavorite): Remove a previously recorded like from a tweet as the authenticated account. Requires a logged-in session. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.
- [Undo Retweet](https://docs.twitterapis.com/docs/reference/write-actions/tweet-unretweet): Undo a previously recorded retweet as the authenticated account. Requires a logged-in session. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.
- [Follow User](https://docs.twitterapis.com/docs/reference/write-actions/user-follow): Follow a user as the authenticated account. Requires a logged-in session for the acting account. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.
- [Unfollow User](https://docs.twitterapis.com/docs/reference/write-actions/user-unfollow): Unfollow a user as the authenticated account. Requires a logged-in session for the acting account. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.
- [Update Avatar](https://docs.twitterapis.com/docs/reference/write-actions/user-update-avatar): Replace the profile picture on the account behind your registered session. Send the image base64-encoded in the request body; there is no URL-fetch form and no multipart form. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Update Banner](https://docs.twitterapis.com/docs/reference/write-actions/user-update-banner): Replace the wide header image on the account behind your registered session. Send the image base64-encoded in the request body; there is no URL-fetch form and no multipart form. Billed at $0.0016 per call. Cost: $0.0016 per call.
- [Update Profile](https://docs.twitterapis.com/docs/reference/write-actions/user-update-profile): Update the profile of the account behind your registered session. Send only the fields you want to change: this is a genuine PARTIAL update, and anything you omit is left exactly as it was rather than being blanked. At least one of name, description, location or url is required. Billed at $0.0016 per call. Cost: $0.0016 per call.

## Resources

- [OpenAPI spec](https://docs.twitterapis.com/openapi.json)
- [Postman collection](https://docs.twitterapis.com/twitterapis.postman_collection.json)
- [Full docs as text](https://docs.twitterapis.com/llms-full.txt)