# TweetStream: real-time social and news feeds over WebSocket for trading systems > TweetStream is a low-latency WebSocket feed for crypto and prediction-market trading systems. TweetStream detects X posts in typically 166 ms, measured from X's post timestamp to first receipt on a TweetStream server. One connection carries posts from the X/Twitter accounts you choose, news from 22 publications, Donald Trump and White House Truth Social posts on Pro, Scale and Ultra Speed, selected Binance Square accounts, pump.fun callouts, and FOMO and charity alerts. TweetStream's Instagram Tracking streams new posts, reels, carousels and stories from the Instagram accounts you pick over its own WebSocket, using the same API key. - `tweet/content` carries the initial usable post. It includes text, author identity, and timestamps; media and reference context are included when available. - `tweet/update` can add reference context or supply the full text of a previously shortened post. Apply it to the existing post by `(platform, tweetId)`. - `tweet/meta` can follow with OCR, token and contract detections, prices, exchange context, and prediction-market context. - Pro, Scale, and Ultra Speed include supported Donald Trump and White House Truth Social posts over WebSocket and Discord. Minimum does not include Truth Social. If Truth Social was already enabled on an active plan, you keep access. - Minimum has no History API access. Pro, Scale, and Ultra Speed include full history replay. - Minimum and Pro have three-day trials. Ultra Speed has a 24-hour trial. - Ultra Speed sends posts and follow alerts from selected X accounts as soon as a TweetStream server receives them, which is where the published detection time stops. Other plans hold posts up to 50 ms and follow alerts 250 ms. - There is no free live plan. The free sandbox needs no key and streams a fixed list of 50 X accounts, 60 seconds late. - Delivery is WebSocket and Discord. There is no built-in Telegram delivery; forward WebSocket events through your own Telegram bot. - TweetStream does not provide Polymarket prices or order execution; use Polymarket's APIs and combine both feeds in the strategy. - TweetStream is independent and is not affiliated with X Corp, Truth Social, TMTG, Donald J. Trump, or Polymarket. ## For AI agents - [Agent quickstart](/docs/agent-quickstart.md): the free sandbox, email-code signup, one payment link, connecting, and MCP. Send `acceptTerms: true` only after the person has read and agreed to the Terms. - [Free sandbox](https://tweetstream.io/api/agent/sandbox): no signup and no key. Connect to `wss://sandbox.tweetstream.io/ws` with subprotocol `tweetstream.v1`. - [Remote MCP server](https://tweetstream.io/mcp): client setup is under "Use the MCP server" in the agent quickstart. - `GET /api/agent/actions`: every account, stream and billing action, with its tier and the schemas of its input and result. See "Account, stream and billing actions" in the agent quickstart. - [OpenAPI](/docs/openapi.json): OpenAPI 3.1 contract for the REST API and every agent route. - [JSON Schema](https://tweetstream.io/schemas/agent-onboarding.schema.json): the agent contract (requests, responses, statuses and error codes). ## Start here - [Full LLM context](/llms-full.txt): All public developer docs in Markdown. - [简体中文 LLM context](/zh-cn/docs/llms-full.txt): 完整的简体中文开发者文档。 - [AsyncAPI](/docs/asyncapi.json): AsyncAPI 3.0 contract for WebSocket v1. - [Machine-readable pricing](/pricing.md): Current Minimum, Pro, Scale, Ultra Speed, and trial facts from the live pricing catalog. - [Live X/Twitter server detection data](/speedcheck): The rolling production report has current p25, p50, p95, sample sizes, UTC windows, and per-account results. The figures exclude customer network transit and trade execution. Compare latency figures only when they measure the same start and end points. This timing claim does not apply to Truth Social. - [Live X/Twitter speed data as JSON](/speedcheck.json): The same rolling report in structured JSON. - [Live X/Twitter speed data as CSV](/speedcheck.csv): Aggregate and per-account rows from the same rolling report. - [Live X/Twitter speed data as Markdown](/speedcheck.md): The same rolling report as percentile tables. ## Docs - [Overview](/docs.md): Connect to TweetStream and find the realtime, event, REST, and example references. - [Discord bot](/docs/discord-bot.md): Set up the TweetStream Discord bot on a paid plan or trial, choose a channel, and manage a shared watchlist of X accounts. - [Billing in Discord](/docs/discord-billing.md): Buy and pay for a TweetStream subscription from the Discord bot, and turn limit alerts on or off. - [Quickstart](/docs/quickstart.md): Open an authenticated TweetStream WebSocket and inspect the first event. - [Production consumer](/docs/production-consumer.md): Build a long-running TweetStream consumer with routing, reconnects, and checkpoints. - [Connection, auth, heartbeat](/docs/connection-auth-heartbeat.md): Choose a WebSocket endpoint, authenticate, and keep the connection responsive. - [Envelope and delivery](/docs/envelope-delivery-recovery-errors.md): Route envelopes, recover after disconnects, and handle public WebSocket errors. - [All events](/docs/payloads-detections-ocr.md): Browse every TweetStream event family and open its payload and integration guide. - [Social content](/docs/social-content.md): Consume Twitter, Truth Social, and Binance Square content through the tweet envelope. - [Tweet meta and lifecycle](/docs/tweet-updates-lifecycle.md): Replace live metadata snapshots, merge tweet updates, then apply delete, pin, and unpin events. - [Profile, follow, affiliate](/docs/profile-follow-affiliate.md): Consume profile, follow, unfollow, and affiliate relationship changes. - [Callouts](/docs/callouts.md): Configure callout alerts and consume account callout events. - [FOMO](/docs/fomo.md): Track FOMO users and coins, read thesis events, and handle observed token verification. - [Charity](/docs/charity.md): Enable charity alerts and consume charity added events. - [News](/docs/news.md): Select publications, consume live news, and paginate news history. - [Control messages](/docs/control.md): Use authentication and handle-management control messages. - [History API](/docs/history-api.md): Query stored account events through the bearer-authenticated History API. - [Accounts and settings](/docs/account-management.md): Add, remove, inspect, and configure accounts through authenticated REST endpoints. - [Examples](/docs/examples.md): Copy and run one TypeScript or Python program that connects, reconnects, merges tweet updates, follows reference chains, and measures latency. - [Instagram WebSocket](/docs/instagram-websocket.md): Connect to the Instagram WebSocket and read post, reel, carousel, and story events. ## API reference - [`GET /api/history` Replay stored events](/docs/api/get-history.md): GET /api/history returns stored post, profile, follow and affiliate events newest first. Filter by handle, date range and type, then page with nextCursor. - [`GET /api/search/posts` Search posts](/docs/api/search-posts.md): GET /api/search/posts returns recent X posts that match a search query, operators included, with engagement counts. One search returns up to 100 posts. - [`GET /api/tweet/{id}` Look up a post](/docs/api/lookup-tweet.md): GET /api/tweet/{id} returns one X post with its author and engagement counts: likes, replies, reposts, quotes, bookmarks and views. Up to 60 lookups a minute. - [`GET /api/user/{id}` Look up an account](/docs/api/lookup-user.md): GET /api/user/{id} returns an X account's profile by numeric ID or handle, plus its pinned post when known. Up to 60 lookups a minute per account. - [`PATCH /api/account-settings` Change an account's Discord webhook and keyword filters](/docs/api/update-account-settings.md): PATCH /api/account-settings changes the Discord webhook and keyword filters for one monitored account. Fields you leave out keep their saved values. - [`POST /api/add-account` Add monitored accounts](/docs/api/add-accounts.md): POST /api/add-account adds one or more X accounts to your watchlist and returns a result for each, so a partial success shows which handles failed. - [`DELETE /api/affiliate-alerts` Disable affiliate-list alerts for an account](/docs/api/disable-affiliate-alerts.md): DELETE /api/affiliate-alerts stops affiliate-list change alerts for one monitored account and returns the account with affiliateAlertsEnabled false. - [`POST /api/affiliate-alerts` Enable affiliate-list alerts for an account](/docs/api/enable-affiliate-alerts.md): POST /api/affiliate-alerts sends an alert whenever a monitored account's affiliate list gains or loses a member. It returns the account and its new setting. - [`DELETE /api/binance-square` Disable a Binance Square account](/docs/api/disable-binance-square-account.md): DELETE /api/binance-square stops posts from one Binance Square account reaching your stream and returns the account with binanceSquareEnabled false. - [`GET /api/binance-square` List available Binance Square accounts and settings](/docs/api/list-binance-square-accounts.md): GET /api/binance-square lists the Binance Square accounts you can stream, each with its display name, profile link and whether you have it enabled. - [`POST /api/binance-square` Enable a Binance Square account](/docs/api/enable-binance-square-account.md): POST /api/binance-square adds posts from one Binance Square account to your stream. Pick a handle from the list endpoint; the response confirms the change. - [`GET /api/callouts` List FOMO users, coins, and pump.fun accounts](/docs/api/list-fomo-and-callout-subscriptions.md): GET /api/callouts lists the FOMO users, FOMO coins and pump.fun callers you track, any pending additions, and each platform's capacity on your plan. - [`PUT /api/callouts` Add a FOMO user, coin, or pump.fun account](/docs/api/add-fomo-or-callout-subscription.md): PUT /api/callouts tracks a FOMO user, FOMO coin or pump.fun caller, with an optional label. It returns the updated list; 409 means that platform is full. - [`DELETE /api/callouts` Remove a tracked or pending FOMO or pump.fun item](/docs/api/remove-fomo-or-callout-subscription.md): DELETE /api/callouts stops tracking a FOMO or pump.fun item by callerId, or cancels a pending one by intentId, and returns the updated subscription list. - [`GET /api/me` Read authenticated account limits and usage](/docs/api/get-account-status.md): GET /api/me returns the key's plan, monitored accounts and limit, open WebSocket connections and limit, and Ultra Speed usage when the plan includes it. - [`DELETE /api/remove-account` Remove monitored accounts](/docs/api/remove-accounts.md): DELETE /api/remove-account removes one or more X accounts from your watchlist and returns a result for each, including handles you were not following. - [`GET /api/ultra/accounts` List Ultra Speed accounts](/docs/api/list-ultra-accounts.md): GET /api/ultra/accounts lists the X accounts selected for Ultra Speed delivery and your plan's Ultra Speed account limit. Accounts without the plan get 404. - [`POST /api/ultra/accounts` Change Ultra Speed accounts](/docs/api/set-ultra-accounts.md): POST /api/ultra/accounts turns Ultra Speed on or off for accounts by handle. Send an Idempotency-Key so a retried request applies the change only once. - [`GET /api/instagram/accounts` List watched Instagram accounts](/docs/api/list-instagram-accounts.md): GET /api/instagram/accounts lists the Instagram accounts on your watchlist, each live, pending or paused, with your account limit and WebSocket access. - [`POST /api/instagram/add-account` Add watched Instagram accounts](/docs/api/add-instagram-accounts.md): POST /api/instagram/add-account adds up to 100 Instagram usernames per request. Accounts already on the list come back as duplicate and count as success. - [`DELETE /api/instagram/remove-account` Remove watched Instagram accounts](/docs/api/remove-instagram-accounts.md): DELETE /api/instagram/remove-account removes up to 100 Instagram usernames per request. Accounts not on the list come back as not_tracked and count as success. - [`GET /api/news/history` Read stored news articles](/docs/api/get-news-history.md): GET /api/news/history returns stored articles from your enabled news sources, newest first, up to 100 per page. Page back with the cursor in nextCursor. - [`GET /api/news/sources` List news sources and current settings](/docs/api/list-news-sources.md): GET /api/news/sources lists every news source with its name and icon, whether it is available right now, and whether it is enabled for your stream. - [`PATCH /api/news/sources` Enable or disable one news source](/docs/api/set-news-source-enabled.md): PATCH /api/news/sources turns one news source on or off for your stream by sourceId. It returns the source; 409 means it is not available right now. - [`GET /api/agent/catalog` Read the public catalog](/docs/api/get-agent-catalog.md): GET /api/agent/catalog lists the plans, prices, limits and trials an agent can buy for a person, with the default payment rail and billing cycle. No key needed. - [`POST /api/agent/checkout` Start a checkout](/docs/api/create-agent-checkout.md): POST /api/agent/checkout returns one payment page for the person to open. Crypto is the default, card is optional, and a remaining trial is used first. - [`POST /api/agent/credentials` Read a stream key](/docs/api/get-agent-credential.md): POST /api/agent/credentials returns the Standard or Ultra Speed stream key for a product the account has. Needs a setup proof from a recent email code. - [`POST /api/agent/credentials/rotate` Rotate a stream key](/docs/api/rotate-agent-credential.md): POST /api/agent/credentials/rotate replaces a stream key at once and shows the new one a single time. Needs a setup proof; a retry with the old key gets 401. - [`POST /api/agent/discord-link` Issue a Discord link](/docs/api/issue-agent-discord-link.md): POST /api/agent/discord-link returns the link a person opens to connect Discord and join the TweetStream community, which some checkouts need first. - [`POST /api/agent/email-code/request` Request an email code](/docs/api/request-agent-email-code.md): POST /api/agent/email-code/request emails the person a 6-digit code. No key needed, and the response is the same whether or not the account already exists. - [`POST /api/agent/email-code/verify` Verify an email code](/docs/api/verify-agent-email-code.md): POST /api/agent/email-code/verify checks the 6-digit code after the person accepts the Terms, and returns the account's API key and a 30-minute setup proof. - [`GET /api/agent/sandbox` Discover the sandbox stream](/docs/api/get-agent-sandbox.md): GET /api/agent/sandbox returns the free sandbox WebSocket URL, its fixed account list, the operations it sends, its delay and its limits. No key needed. - [`POST /api/agent/scale-trial` Start a Scale trial](/docs/api/start-agent-scale-trial.md): POST /api/agent/scale-trial starts a Scale trial with a code from the TweetStream team. Reuse the Idempotency-Key on retries to get the same result back. - [`GET /api/agent/status` Read onboarding status](/docs/api/get-agent-status.md): GET /api/agent/status reports progress for one product or one checkout and the next step, such as open_payment or wait. Poll at next.afterSeconds. - [`GET /api/agent/actions` List agent actions](/docs/api/list-agent-actions.md): GET /api/agent/actions lists every agent action with its tier, MCP tool, scope, and the JSON Schemas of its input and result. No API key needed. - [`POST /api/agent/actions/discord_community` discord_community](/docs/api/agent-action-discord-community.md): Joins the TweetStream Discord server with the linked Discord account, checks verification, or sends a test billing reminder. Needs a recent email-code sign-in. - [`POST /api/agent/actions/get_account` get_account](/docs/api/agent-action-get-account.md): Reads the account's email, name, referral code, credits, stream setup progress and Discord standing. The email stays masked without a recent email-code sign-in. - [`POST /api/agent/actions/update_account` update_account](/docs/api/agent-action-update-account.md): Names the account, applies a referral code, and turns Discord billing reminders and limit alerts on or off. Each change is applied or refused on its own. - [`POST /api/agent/actions/cancel_pending_payment` cancel_pending_payment](/docs/api/agent-action-cancel-pending-payment.md): Holds a cancellation of an open stablecoin payment, scheduled Scale limit change or open Ultra Speed checkout. confirm_action runs it with the emailed code. - [`POST /api/agent/actions/change_billing` change_billing](/docs/api/agent-action-change-billing.md): Holds a plan, term, limit, pause, cancel or auto-renew change and returns its price and date. Nothing changes until confirm_action runs it with the code. - [`POST /api/agent/actions/change_renewal_rail` change_renewal_rail](/docs/api/agent-action-change-renewal-rail.md): Switches a subscription's renewals between card and stablecoins. A payment due now comes back as a link the person opens. Needs a recent email-code sign-in. - [`POST /api/agent/actions/get_billing` get_billing](/docs/api/agent-action-get-billing.md): Reads each subscription's plan, price, status, renewal and available changes, plus open and recent stablecoin payments and any open checkout. API key only. - [`POST /api/agent/actions/get_billing_portal_link` get_billing_portal_link](/docs/api/agent-action-get-billing-portal-link.md): Returns a billing portal link where the person manages their card and invoices. Needs the API key and a setup proof from a recent email-code sign-in. - [`POST /api/agent/actions/get_payment_link` get_payment_link](/docs/api/agent-action-get-payment-link.md): Returns a link the person opens to pay a subscription's open invoice or stablecoin renewal, or to pay by card an invoice waiting on stablecoins. API key only. - [`POST /api/agent/actions/confirm_action` confirm_action](/docs/api/agent-action-confirm-action.md): Runs a held billing change once the person reads back the 6-digit code emailed for it. Calling it again returns the same outcome without repeating the change. - [`POST /api/agent/actions/get_pending_action` get_pending_action](/docs/api/agent-action-get-pending-action.md): Reads a held change: what it will do, whether a confirmation code was sent and, once confirmed, its outcome. Works with the API key alone, over HTTP or MCP. - [`POST /api/agent/actions/request_confirmation_code` request_confirmation_code](/docs/api/agent-action-request-confirmation-code.md): Emails the person a 6-digit code for one held change, naming the change, its price and its date. Asking again replaces the earlier code. API key only. - [`POST /api/agent/actions/get_accounts` get_accounts](/docs/api/agent-action-get-accounts.md): Reads the accounts a product streams: the X watchlist with each account's settings, the Ultra Speed selection, or the Instagram watchlist. API key only. - [`POST /api/agent/actions/get_delivery` get_delivery](/docs/api/agent-action-get-delivery.md): Reads the default keyword filters and Discord webhook, feed toggles, Binance Square accounts, news sources, callouts and the Instagram Discord destination. - [`POST /api/agent/actions/manage_callouts` manage_callouts](/docs/api/agent-action-manage-callouts.md): Adds or removes the callout accounts your stream tracks, or cancels one that is still pending. Works with the API key alone, over HTTP or the MCP tool. - [`POST /api/agent/actions/select_trial_accounts` select_trial_accounts](/docs/api/agent-action-select-trial-accounts.md): During a trial, picks which saved X accounts the trial streams, by X account ID. Works with the API key alone, over HTTP or the MCP tool of the same name. - [`POST /api/agent/actions/set_delivery` set_delivery](/docs/api/agent-action-set-delivery.md): Changes keyword filters, Discord webhooks, event types, affiliate alerts, Binance Square, news sources, and the Truth Social and charity feeds. API key only. ## Full public docs ## TweetStream developer docs Connect first, then use focused references for the WebSocket protocol, events, REST APIs, and complete consumers. Canonical URL: https://tweetstream.io/docs ### Start streaming - [Complete WebSocket example](https://tweetstream.io/docs/examples#run): Download one file, run it with your API key, and watch events arrive. - [Production consumer](https://tweetstream.io/docs/production-consumer): Add routing, reconnects, and checkpoints. - [Event reference](https://tweetstream.io/docs/payloads-detections-ocr): Find the payload for each event operation. - [REST reference](https://tweetstream.io/docs/history-api): Replay stored events and manage account settings. ### Choose a base URL Connect to `wss://ws-iad.tweetstream.io/ws` in the USA or `wss://ws-global.tweetstream.io/ws` elsewhere. REST requests use `https://api.tweetstream.io`. - [Connection details](https://tweetstream.io/docs/connection-auth-heartbeat#base-urls): Every endpoint, authentication method, and heartbeat rule. ### Use machine-readable contracts - [OpenAPI 3.1](https://tweetstream.io/docs/openapi.json): Generate REST clients from the public endpoint contract. - [AsyncAPI 3.0](https://tweetstream.io/docs/asyncapi.json): Inspect every WebSocket channel, operation, and payload schema. - [LLM context](https://tweetstream.io/docs/llms-full.txt): Load the complete public docs as Markdown. ## Agent quickstart An agent can run every step here as an HTTP call for the person it works for, without opening the dashboard: try the free sandbox, sign up with an email code, send one payment link, then connect. Canonical URL: https://tweetstream.io/docs/agent-quickstart ### Try the sandbox first The sandbox needs no account and no key. It streams posts from a fixed list of 50 X accounts, 60 seconds late, as the same `tweet` envelopes the paid stream sends: `content`, `update`, `meta`, `delete`, `pin` and `unpin`. Code written against it runs on the paid stream once you change the host and add a key. Each client can hold 2 connections, and a session ends after 30 minutes; reconnect to keep going. The first frame is `sandbox_welcome`. Requests to add or remove accounts are answered with an error. Sandbox accounts: `@_richardteng`, `@a1lon9`, `@binance`, `@binancewallet`, `@binancezh`, `@blknoiz06`, `@bnbchain`, `@brian_armstrong`, `@cb_doge`, `@cobie`, `@coinbase`, `@cz_binance`, `@deitaone`, `@elonmusk`, `@eth_cedric`, `@fern`, `@finkd`, `@firstsquawk`, `@flapdotsh`, `@fourdotmemezh`, `@heyibinance`, `@jensenhuang`, `@jerallaire`, `@jessepollak`, `@justinsuntron`, `@meadgod`, `@mert`, `@nikitabier`, `@nina_rong`, `@openai`, `@pmarca`, `@polymarket`, `@ponsdotfamily`, `@pumpfun`, `@realdonaldtrump`, `@robinhoodapp`, `@robinhoodcrypto`, `@sama`, `@saylor`, `@solana`, `@spacex`, `@theunipcs`, `@toly`, `@unusual_whales`, `@vitalikbuterin`, `@vladtenev`, `@watcherguru`, `@whitehouse`, `@zachxbt`, `@zerohedge`. #### Read the sandbox details ```bash curl -s https://tweetstream.io/api/agent/sandbox ``` #### Connect to the sandbox ```bash npx wscat -c wss://sandbox.tweetstream.io/ws -s tweetstream.v1 ``` #### First frame ```json { "v": 1, "t": "control", "op": "sandbox_welcome", "ts": 1793275200000, "d": { "signupUrl": "https://tweetstream.io/llms.txt", "accounts": 50, "delaySeconds": 60, "sessionSeconds": 1800 } } ``` ### Sign up with an email code Sign-up takes two calls. The first emails a 6-digit code to the person. The second trades that code for the account's API key. The first response is the same whether or not the email already has an account, and an existing account gets its current key back. The code expires at `expiresAt`. A new one can be requested after `resendAt`. `setupProof` lasts 30 minutes. You need it to issue a Discord link and to read a key again. If it expires, request and verify a new code. > Ask the person before you verify > > Send `acceptTerms: true` only after the person has read the Terms and said yes. Ask for the code and their agreement in the same message. > > - [Terms of Service](https://tweetstream.io/terms) #### Email a code ```bash curl -s https://tweetstream.io/api/agent/email-code/request \ -H 'Content-Type: application/json' \ -d '{"email":"alice@example.com"}' ``` #### 202 response [Use the first complete copy of this example.](https://tweetstream.io/docs/api/request-agent-email-code#responses) #### Verify the code ```bash # Only after the person gave you the code and accepted the Terms. curl -s https://tweetstream.io/api/agent/email-code/verify \ -H 'Content-Type: application/json' \ -d "{\"challengeId\":\"$CHALLENGE_ID\",\"code\":\"$EMAIL_CODE\",\"acceptTerms\":true}" ``` #### 200 response [Use the first complete copy of this example.](https://tweetstream.io/docs/api/verify-agent-email-code#responses) #### Store the key ```bash # Keep both out of chat, commits and logs. export TWEETSTREAM_API_KEY='' export TWEETSTREAM_SETUP_PROOF='' ``` ### Start a checkout Ask the person which plan they want, then start a checkout. The person gets one payment link, and that page shows the price before anything is charged. Crypto is the default: the page takes payment from a crypto wallet. Add `"paymentRail":"CARD"` to pay by card instead. - `planType` is `BASIC` for Minimum or `ELITE` for Pro. `billingCycle` is `MONTHLY`, `QUARTERLY`, `SEMIANNUAL` or `YEARLY`. - If the account still has a trial, the checkout uses it: `offer.mode` is `trial` and `amountDueNow` is 0. - `offer.renewal.amount` is the first charge, on `renewal.at`. `renewal.thenAmount` is every charge after that. They differ when a trial deposit is taken off the first charge. - Send the setup proof with the checkout. If the purchase needs Discord, the response then has the join link. Without a valid proof, `next` is `reverify_email`: request and verify a new code, then send the same checkout again with the new proof. - Make one `Idempotency-Key` per purchase and reuse it on retries, so a retry returns the same checkout. - Give the person `paymentUrl` and let them pay there. Then poll `next.pollUrl`. - `GET /api/agent/catalog` lists every plan, price and limit. #### Start a checkout ```bash CHECKOUT_KEY=$(uuidgen) # one key per purchase; reuse it on retries curl -s https://tweetstream.io/api/agent/checkout \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" \ -H "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ -H "Idempotency-Key: $CHECKOUT_KEY" \ -H 'Content-Type: application/json' \ -d '{"family":"BASE","planType":"ELITE","billingCycle":"MONTHLY"}' ``` #### 201 response [Use the first complete copy of this example.](https://tweetstream.io/docs/api/create-agent-checkout#responses) #### Or: pay by card (run one checkout, not both) ```bash # Instead of the crypto checkout above, not after it: a new purchase gets its own key. CARD_CHECKOUT_KEY=$(uuidgen) curl -s https://tweetstream.io/api/agent/checkout \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" \ -H "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ -H "Idempotency-Key: $CARD_CHECKOUT_KEY" \ -H 'Content-Type: application/json' \ -d '{"family":"BASE","planType":"ELITE","billingCycle":"MONTHLY","paymentRail":"CARD"}' ``` ### Join Discord when asked Some purchases need the person in the TweetStream Discord server first: a paid Base plan, and every Ultra Speed or Instagram Tracking purchase. A Base trial does not. The checkout then returns `community_required`. - With the setup proof, the checkout response includes the join link. Without a valid proof, `next` is `reverify_email`. To get the link again later, call `POST /api/agent/discord-link` with the proof. - Give the person the link. Status reads return `wait_for_discord` until they have joined, then `resume_checkout`. - Send the same checkout request with the same `Idempotency-Key`. The response has the payment link. - Status reads never include the join link. #### 200 response [Use the first complete copy of this example.](https://tweetstream.io/docs/api/create-agent-checkout#responses) ### Poll until ready After a step the person takes, poll `next.pollUrl` every `next.afterSeconds` seconds. Every response has one `status` and one `next`, and `next.who` says whether you or the person acts. Readiness can change later, for example when a trial ends. If the stream refuses the key, read status again. | Status | Meaning | Next | | --- | --- | --- | | `awaiting_email` | A code was emailed. | `verify_email`: ask the person for the code and their agreement to the Terms. | | `payment_required` | No plan or trial for this product yet. | `create_checkout`, `open_payment` (give the person the link), or `resume_checkout`. | | `community_required` | This purchase needs the person in the TweetStream Discord server. | `join_discord`, `issue_discord_link`, `wait_for_discord` or `reverify_email`. | | `processing` | A payment is being confirmed. | `wait`: poll again. | | `ready` | The product is active. | `select_accounts`, `save_credential` or `connect`. `optionalSteps` may offer the Discord link. | | `closed` | The checkout expired or was canceled, or the plan it bought has ended. | `create_checkout` with a new key. | | `blocked` | Support has to look at the account, or Ultra Speed has more accounts selected than the plan allows. | `resolve`: tell the person, or turn Ultra accounts off. | #### Poll status ```bash until curl -s "https://tweetstream.io/api/agent/status?family=BASE" \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" | grep -q '"status":"ready"'; do sleep 5 done ``` #### Ready response [Use the first complete copy of this example.](https://tweetstream.io/docs/api/start-agent-scale-trial#responses) ### Pick accounts and connect Add the X accounts to stream, then open `stream.url` with the key in the `Authorization` header. - [WebSocket quickstart](https://tweetstream.io/docs/quickstart): Print the first event, then route by `t` and `op`. - [Complete example](https://tweetstream.io/docs/examples): A TypeScript or Python consumer that reconnects and merges updates. - If your WebSocket client can't set headers, send the key as the subprotocol `tweetstream.auth.token.` next to `tweetstream.v1`. Never put it in the URL. - From here, the WebSocket quickstart and the complete examples apply as written. #### Add accounts ```bash curl -s https://tweetstream.io/api/add-account \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"accounts":["coinbase","binance"]}' ``` #### Connect ```bash npx wscat -c wss://ws-global.tweetstream.io/ws -s tweetstream.v1 \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` ### Error codes Errors have the shape `{"error":{"code","message","retryAfterSeconds"},"next"}`. Branch on `code`; `message` is written for people. Every error has a `next`: do that. `retry` means send the same request again after `next.afterSeconds`. | Code | HTTP | What to do | | --- | --- | --- | | `INVALID_REQUEST` | 400 | Fix the body or headers. Unknown fields are rejected. | | `INVALID_CODE` | 400 | Ask the person to check the code, or request a new one. | | `TERMS_NOT_ACCEPTED` | 400 | Ask the person to accept the Terms, then send `acceptTerms: true`. | | `INVALID_API_KEY` | 401 | Check `TWEETSTREAM_API_KEY`. A rotated key stops working. | | `REVERIFY_EMAIL` | 401 | The setup proof is missing or expired. Request and verify a new code. | | `ACCOUNT_RESTRICTED` | 403 | Stop and tell the person to contact support. | | `ORIGIN_REJECTED` | 403 | Call from a server or terminal, without a browser `Origin` header. | | `CHECKOUT_NOT_FOUND` | 404 | Check `checkoutId`, or read status by `family`. | | `NOT_ENTITLED` | 404 | Finish the checkout first, then poll status until `ready`. | | `PAYMENT_LINK_INVALID` | 404 | Start a new checkout to get a new payment link. | | `DISCORD_LINK_INVALID` | 404 | Issue a new Discord link. | | `IDEMPOTENCY_CONFLICT` | 409 | This `Idempotency-Key` was used for a different body. Use a new key. | | `CHECKOUT_CONFLICT` | 409 | Another checkout for this product is open. Read status and follow it. | | `OFFER_CHANGED` | 409 | The price or plan changed. Show the person the new offer. | | `TRIAL_UNAVAILABLE` | 409 | No trial for this account. Start a paid checkout. | | `TRIAL_AUTHORIZATION_REQUIRED` | 409 | This trial needs a code from the TweetStream team. | | `RATE_LIMITED` | 429 | Wait `retryAfterSeconds`, then retry. | | `ACTIVATION_BUDGET_EXHAUSTED` | 429 | Too many trial starts. Wait `retryAfterSeconds`. | | `TEMPORARILY_UNAVAILABLE` | 503 | Retry with backoff and the same `Idempotency-Key`. | | `ACTION_NOT_FOUND` | 404 | No action has that name. Read the list at `GET /api/agent/actions`. | | `ACTION_REFUSED` | 409 | Read `error.message` and `error.reason`. This call changed nothing. | | `CONFIRMATION_NOT_FOUND` | 404 | No held change with that `pendingActionId` for this API key or connection. It may belong to a replaced key. Call the action again. | | `CONFIRMATION_EXPIRED` | 409 | The held change expired. Call the action again for a new one. | ### Keep the key safe - Store the key in `TWEETSTREAM_API_KEY` or a secret store. Don't paste it into chat, commit it, or print it. - Send it only in the `Authorization` header or the auth subprotocol. URLs end up in logs, so never use `?apiKey=`. - If the key was exposed, for example committed, logged or left in a shared transcript, rotate it: `POST /api/agent/credentials/rotate` with the setup proof, or the `rotate_api_key` MCP tool. The old key stops working at once and the response holds the new key. Regenerate key on the dashboard's API tab does the same. - Rotating the main key (`BASE`) also ends the setup proof, because the proof belongs to that key: verify a new code before the next call that needs one. Rotating the Ultra Speed key (`ULTRA`) leaves the setup proof working. - Treat `setupProof` as a secret too. It expires after 30 minutes. #### Rotate the key ```bash # Needs a setup proof from the last 30 minutes. If it expired, verify a new email code first. curl -s https://tweetstream.io/api/agent/credentials/rotate \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" \ -H "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ -H 'Content-Type: application/json' \ -d '{"family":"BASE"}' ``` ### Use the MCP server Agents that support remote MCP servers can run the same flow as tools. The server is `https://tweetstream.io/mcp`. The person signs in once in a browser with an email code and accepts the Terms there. The client config holds no secrets. #### Claude Code ```bash claude mcp add --transport http tweetstream https://tweetstream.io/mcp # Then run /mcp in Claude Code and sign in. ``` #### Cursor (~/.cursor/mcp.json) ```json { "mcpServers": { "tweetstream": { "url": "https://tweetstream.io/mcp" } } } ``` #### Codex ```bash codex mcp add tweetstream --url https://tweetstream.io/mcp codex mcp login tweetstream ``` ### Account, stream and billing actions Most of what the dashboard does to an account, its stream and its billing is also an HTTP call, with an MCP tool of the same name. `GET /api/agent/actions` lists them, with each action's tier and the JSON Schema of its input and result. Call one with `POST /api/agent/actions/`, the API key, and the input as the JSON body. To end a trial early, change Scale limits or undo a scheduled term change, send the person to the dashboard. `get_account` masks the email (`j***@example.com`) unless the request proves a recent sign-in: `X-TweetStream-Setup-Proof` over HTTP, or, over MCP, an email-code sign-in in the last 30 minutes that granted `tweetstream:settings`. > Links are for the person > > Payment pages, wallet signatures, card entry and the billing portal come back as links. Give the link to the person. Don't open it, fill it in or sign for them. | Tier | Covers | What it needs | | --- | --- | --- | | `read` | Reading the account, its stream settings and billing, and payment links. Changing stream settings: filters, webhooks, feeds, callouts and which accounts a trial streams. | The API key. | | `recent` | Changes to the account itself: its name, a referral code, Discord, Discord billing reminders and limit alerts, how renewals are paid, and the billing portal link. | The API key and `X-TweetStream-Setup-Proof` from an email code verified in the last 30 minutes. Over MCP, the person signs in again when asked. | | `confirm` | Money moves and cancellations: plan and term changes, Instagram and Ultra Speed account limits, pauses, turning off auto-renew, and cancelling a subscription or a pending payment. | A code emailed to the person, which they read back to you. The steps are below. | #### List the actions ```bash curl -s https://tweetstream.io/api/agent/actions ``` #### Read the account ```bash curl -s https://tweetstream.io/api/agent/actions/get_account \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" \ -H 'Content-Type: application/json' \ -d '{}' ``` #### Confirm a money move or cancellation These changes wait for a code the person reads back to you. Over MCP, call the tools with the same names. > Steps > > A held change lasts at most 5 minutes, and its code expires with it. > > 1. Call the action, for example `change_billing`. It answers `confirmation_required` with `pendingAction`: its `id`, a summary, the price and when it takes effect. Nothing has changed yet and no email was sent. Show the person the summary. > 2. If a cancellation's quote has a `saveOffer`, ask the person whether they want it before you request a code. To take it, call `change_billing` again with `{ "kind": "save_offer", "offer": }`. > 3. If they agree to the change, call `request_confirmation_code` with `pendingActionId` set to that `id`. The person gets an email naming the change, the amount and the date. Keep the `challengeId` it returns. > 4. Ask the person for the 6-digit code. > 5. Call `confirm_action` with `pendingActionId`, `challengeId` and `code`. It makes the change exactly as it was shown. > 6. If `confirm_action` answers `in_progress`, wait the `retryAfterSeconds` it returns, then call `get_pending_action`. > 7. If the response is lost, call `get_pending_action` with the `pendingActionId` instead of starting over. Calling `confirm_action` again returns the same outcome, and the change never runs twice. ##### Confirm with the code ```bash # Run only after the person reads you the code from the email. curl -s https://tweetstream.io/api/agent/actions/confirm_action \ -H "Authorization: Bearer $TWEETSTREAM_API_KEY" \ -H 'Content-Type: application/json' \ -d @- <"}` instead. ## Set up the Discord bot Get posts from the X accounts you track in your own Discord channel at standard speed. The bot is included with paid plans and trials and needs no code. Canonical URL: https://tweetstream.io/docs/discord-bot ### Sign up and verify Discord Sign up with email or Discord and start a trial or plan. Your dashboard shows the next step. In the dashboard, select Verify Discord. Link your Discord account if you signed up with email, authorize it to join the TweetStream community, and accept the rules in Discord. The dashboard checks your membership automatically. Verification opens the member channels and Speed Check. Your feed goes to your own server, not the community server. - [Start a trial](https://tweetstream.io/signup): Create an account and choose the plan to try. ### Install and set up your feed - Select Add bot to your server in the dashboard. An admin can install it for you. To connect the server, your linked Discord account needs Manage Server or Administrator permission. - Run `/setup` in your server and choose a feed channel. Give the bot View Channel, Send Messages, Embed Links, and Attach Files permission. Only your linked Discord account can manage the feed. ### Manage your feed and watchlist - Use `/add` to save an X account, `/remove` to stop tracking it, and `/list` to see active and paused accounts. The bot and dashboard share this watchlist with your other eligible TweetStream delivery paths. - With Ultra Speed, `/add-ultra` turns on Ultra for an X account and `/remove-ultra` turns it off. `/add-ultra` saves the account to your watchlist first if it isn't there yet. Without Ultra Speed, `/add-ultra` shows the plan, and the account turns on once the plan starts. `/list` marks the accounts that have Ultra. - Use `/channel` to change channels. One TweetStream account connects to one server. To move the feed, run `/setup` in the new server and confirm. Your linked Discord account needs Manage Server or Administrator permission there; delivery to the old server then stops. - Run `/me` for a private view of your plan and tracking limit. Paid renewal dates and trial end dates appear when applicable. Base and Ultra subscriptions appear separately. - The bot keeps X accounts active up to your plan's account limit: accounts you picked during a trial first, then your oldest saved accounts. The rest pause but stay saved. Paid Ultra Speed includes Minimum, so Ultra Speed on its own has a limit of 50. An Ultra Speed trial on its own is limited to the accounts the trial covers, and those accounts get Discord delivery only; WebSocket access to them needs a base plan or trial. Without a paid plan, trial, or Ultra Speed subscription, the limit is 0, so every account pauses until you start one. Check `/list` before removing an account you still need elsewhere. - A successful `/add` confirms tracking. It does not mean a post has already arrived; wait for the account to publish again. ### Limits, speed, and plans The bot delivers X posts. Accounts covered by an Ultra subscription use Ultra speed; other accounts use standard speed. With an Instagram Tracking plan, the bot can also post the Instagram accounts on that plan to your channel. The bot and your saved watchlist stay on the same account when you change plans. WebSocket access, other sources, history, and customer webhooks require an applicable paid plan or eligible trial. Each delivery path follows its own limits. - [Compare plans](https://tweetstream.io/pricing): Check source access, delivery options, and account limits. ### Billing and trial reminders Paid plans get renewal reminders by Discord DM; trials get trial-ending notices. Accounts without a plan or trial get no billing reminders. Reminders default on when you first link Discord. Manage reminders and send a test DM in Dashboard → Plan. You do not need to install the bot or run `/setup` to receive reminders. Reminders go to your linked Discord account. Discord privacy settings may block DMs; billing details stay out of public channels. Email reminders continue independently. Minimum and Pro trial notices arrive within the final 24 hours; Ultra trial notices within the final 12 hours. Card renewal notices start three days before renewal. Stablecoin notices start three days before monthly renewal or fourteen days before annual renewal. Each notice shows the payment action or access-end date. - [Manage Discord reminders](https://tweetstream.io/dashboard?tab=plan): Open the reminder setting in Dashboard → Plan. - [Billing in Discord](https://tweetstream.io/docs/discord-billing): Buy, pay for, and change your plan with /billing. ### Troubleshooting - Run `/help` in your server or in a DM with the bot to see every command. - Already have an account? Sign in before linking Discord. If your Discord identity belongs to another account, use that account or contact support; another signup will not bypass the link. - Membership pending? Accept the community rules in Discord and check again. If verification is unavailable, retry later. - No posts? Check `/list`, the selected channel, and the bot's permissions. The account may not have posted since you added it. - Existing customers can dismiss the dashboard link or join prompt. It does not reset their server or block existing access. ## Billing in Discord Run `/billing` in your server or in a DM with the bot to buy a plan, pay a bill, or change your subscription. Only you can see the replies. Canonical URL: https://tweetstream.io/docs/discord-billing ### Get a plan from Discord - [Compare plans](https://tweetstream.io/pricing): See prices, limits, and what each plan includes. - Run `/billing`, or press Get a plan or Billing on `/me`, a server panel, or your trial welcome message. Choose Base, Instagram Tracking, or Ultra Speed, then a plan and a term. For Scale, the button opens our contact page. - Choose how to pay: Start free trial with card, Pay with USDC, or Pay with USDT. Choosing a payment method accepts the Terms. If your Discord account isn't linked to TweetStream yet, this creates a TweetStream account for it. If you already have an account, press Link account first so the plan goes on that account. - Card or free trial: the reply has a button that opens a checkout page in your browser, where you enter your card. Your bank may ask you to confirm. Free trials need a card, and each card gets one trial of each product. If yours already had one, the reply says so and you can still pay. - USDC or USDT: the reply shows the exact amount, a Solana address, a QR code, and when the request expires. Send exactly that amount of that token on Solana before then. Open in wallet hands the payment to a Solana wallet on your device, and Pay on web shows the same payment in your browser. - Ultra Speed starts with no X accounts selected. Once it's active, run `/add-ultra` in your server to choose them. If you started from `/add-ultra`, that account turns on by itself and the reply says so. - The reply updates itself. It shows Payment received while the payment is applied, then something like "Paid. Pro is active through 16 Nov." or "Trial active until 19 Oct." once your subscription is active. ### Pay a renewal or a bill - Renewal reminders in your DMs have a Pay button. It always opens what you owe now, so an older reminder still pays the current amount. `/billing` also shows Pay when a payment is due. - Stablecoin renewals work like a new plan: exact amount, Solana address, QR code, and expiry time. If the request expired, press Pay or run `/billing` to get a new one. - If a card payment fails or needs bank approval, Pay opens the invoice in your browser, where you can pay or approve it. ### Limit alerts - [Discord limit alerts](https://tweetstream.io/dashboard?tab=plan): Turn alerts on or off in Dashboard → Plan. - The bot sends you a DM when an account limit is nearly full and again when it is full, for example "18 of 20 accounts used. Need more room?" Nearly full means 10% of the limit or one account is left, whichever is more. Upgrade opens your plan options, and nothing is charged until you confirm. - Alerts cover your X account limit, your Instagram Tracking accounts, and your Ultra Speed accounts. You get at most one alert a week and two in 30 days. There are no alerts during a trial, while a subscription is paused, canceling, or unpaid, or when a bigger plan wouldn't raise that limit. - Alerts are on by default and go to your linked Discord account, even if billing reminders are off. To turn them off, press Turn off alerts on any alert, or use the Discord limit alerts switch in Dashboard → Plan. Email and billing reminders don't change. - When `/add` hits your account limit, its reply also has an Upgrade button. ### Payment safety - The bot never asks for card details in Discord. You enter a card only on the checkout or invoice page in your browser, and payment buttons open tweetstream.io first. - Billing menus expire after 15 minutes, and a stablecoin request expires at the time it shows. - Billing replies are private, and their buttons only work for the Discord account that opened them. ### FAQ - [Contact support](https://tweetstream.io/contact): Tell us what you paid and when, and we'll check it. #### The pay link expired Run `/billing` again, or press Pay on your renewal reminder. You get a new request for the current amount. Don't send funds to a request that has expired. #### I paid but got no confirmation A stablecoin payment can take a few minutes to apply. Discord only lets the bot update a reply for about 15 minutes, so a later confirmation comes as a DM if billing reminders are on. Run `/me` or open Dashboard → Plan to see your plan. If it still isn't active, contact support with the time you paid and the transaction ID. #### I use a different Discord account Billing goes to the TweetStream account linked to the Discord account you run `/billing` from. If that Discord account isn't linked, paying creates a new TweetStream account. To pay for your existing account, link this Discord account first with Link account in the plan reply, or select Change on the Discord tab of your dashboard. One Discord account links to one TweetStream account. #### The bot says "This menu expired" Billing menus last 15 minutes. Run `/billing` for a new one. The Billing button on `/me` and the buttons in your DMs keep working. ## WebSocket quickstart Add one monitored account, open a server-side WebSocket, and print each v1 envelope. Canonical URL: https://tweetstream.io/docs/quickstart ### Run a 5-minute smoke test Add one monitored account, copy the example, and run it. `TweetStream connected` confirms authentication. Events appear when that account posts. #### Run the TypeScript smoke test ```typescript // bun add ws // TWEETSTREAM_API_KEY=ts_... bun run smoke.ts import WebSocket from "ws"; const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) { throw new Error("Missing TWEETSTREAM_API_KEY"); } const ws = new WebSocket("wss://ws-global.tweetstream.io/ws", [ "tweetstream.v1", `tweetstream.auth.token.${apiKey}`, ]); ws.on("open", () => { console.log("TweetStream connected"); }); ws.on("message", (raw) => { const event = JSON.parse(raw.toString()); console.log(event.t, event.op, event.d); }); ws.on("close", (code, reason) => { console.log("TweetStream closed", code, reason.toString()); }); ws.on("unexpected-response", (_request, response) => { console.error( "Connection rejected", response.statusCode, response.statusMessage, ); response.resume(); process.exitCode = 1; }); ws.on("error", (error) => { console.error("WebSocket error", error.message); }); ``` ### Route operations Each event names its family in `t` and its operation in `op`. The delivery reference lists all 19 server operations. - [All operations](https://tweetstream.io/docs/envelope-delivery-recovery-errors#operations): Family, operation, and meaning for every server event. ### Make it durable - [Connection details](https://tweetstream.io/docs/connection-auth-heartbeat): Choose an endpoint and understand authentication and heartbeat behavior. - [Production consumer](https://tweetstream.io/docs/production-consumer): Add reconnects, event routing, and recovery checkpoints. ## Build a production consumer Route known operations, reconnect with backoff, and make every side effect safe to repeat. Canonical URL: https://tweetstream.io/docs/production-consumer ### Reconnect with backoff Start from the reconnecting Node.js or Python consumer, then route every operation through one exhaustive handler. - [Reconnecting consumers](https://tweetstream.io/docs/connection-auth-heartbeat#connect): Node.js and Python clients with exponential backoff. - [Complete router](https://tweetstream.io/docs/production-consumer#complete-router): Typed handlers for all 19 server operations. ### Route every server operation This TypeScript router covers all 19 server operations after validation. Use the executable reference consumer for the runtime decoder. Ignore unknown operations without closing the socket. Keep the handlers small. Persist the receipt and local projection before calling a strategy, notification, or execution boundary. #### Exhaustive TypeScript router ```typescript type VerifiedType = 'blue' | 'business' | 'government' | 'verified' | 'none'; type TweetVerifiedLabel = { badge: string | null; description: string; url: string | null; }; type TweetAuthor = { banner?: string; bio?: string; followersCount?: number; followingCount?: number; id?: string; joinedAt?: number; location?: string; metrics?: { likes?: number; tweets?: number; }; // Includes a leading @ when present, for example "@elonmusk". handle?: string; name?: string; platform?: 'twitter' | 'truth_social' | 'binance_square'; profileImage?: string; // The account's own website, when it has one. url?: string; verifiedLabel?: TweetVerifiedLabel; verifiedType?: VerifiedType; }; type Media = { url: string; } & ( | { type: 'video'; // Every video is a progressive MP4. A public still poster is included // when available. thumbnail?: string; } | { type?: 'image' | 'gif'; thumbnail?: string; } ); type TweetUrl = { url: string; name?: string; tco?: string; }; type TweetMention = { handle?: string; id?: string; name?: string; }; type TweetArticle = { description?: string; id?: string; publishedAt?: number; text?: string; thumbnail?: string; title: string; updatedAt?: number; url: string; }; type TweetPollChoice = { id?: string; image?: string; label: string; votes?: number; }; type TweetPoll = { choices: TweetPollChoice[]; endsAt?: number; totalVotes?: number; updatedAt?: number; }; type TweetContentKind = 'post' | 'reply' | 'quote' | 'retweet'; type TweetReference = { article?: TweetArticle; type: 'reply' | 'quote' | 'retweet'; // Absent until known: a partial ref has only author; a later tweet/update completes it. tweetId?: string; text?: string; translatedText?: string; author?: TweetAuthor; media?: Media[]; poll?: TweetPoll; quoted?: TweetReference; subtweet?: TweetReference; }; type TweetContent = { tweetId: string; kind: TweetContentKind; // Original tweet text when the event includes both original and translated text. text: string; // Translation, present only when available. translatedText?: string; createdAt: number; author: TweetAuthor; article?: TweetArticle; link?: string; media?: Media[]; mentions?: TweetMention[]; poll?: TweetPoll; receivedAt?: number; urls?: TweetUrl[]; ref?: TweetReference; // The post a reply also quotes. A quote keeps the post it quotes in ref. quoted?: TweetReference; }; type TweetMeta = { tweetId: string; // Pair with tweetId when merging enrichment. When omitted, use twitter. platform?: 'twitter' | 'truth_social' | 'binance_square'; ocr?: { text: string; }; detected?: { tokens?: Array<{ symbol?: string; name?: string; contract?: string; chain?: string; networkId?: number; priceUsd?: number; sources: Array<'text' | 'ocr'>; }>; cex?: Array<{ exchange: 'bybit' | 'binance' | 'hyperliquid'; symbol?: string; priceUsd?: number; url?: string; baseAsset?: string; quoteAsset?: string; sources: Array<'text' | 'ocr'>; }>; prediction?: Array<{ exchange: 'polymarket' | 'kalshi'; marketId?: string; title?: string; priceUsd?: number; url?: string; sources: Array<'text' | 'ocr'>; }>; }; }; type TweetUpdate = { tweetId: string; // Pair with tweetId. When absent, use author.platform, then twitter. platform?: 'twitter' | 'truth_social' | 'binance_square'; article?: TweetArticle; kind?: TweetContentKind; translatedText?: string; author?: TweetAuthor; media?: Media[]; mentions?: TweetMention[]; poll?: TweetPoll; receivedAt?: number; urls?: TweetUrl[]; ref?: TweetReference; quoted?: TweetReference; } & ( | { text?: string; textUpdateType?: never; } | { text: string; // Supplies the full text of a previously shortened post. Not an edit. textUpdateType: 'completion'; } ); type TweetDeleteEvent = { tweetId: string; // When absent, use author.platform, then twitter. platform?: 'twitter' | 'truth_social' | 'binance_square'; eventId?: string; deletedAt?: number; receivedAt?: number; author?: TweetAuthor; text?: string; }; type TweetPinEvent = { tweetId: string; // When absent, use tweet.author.platform or author.platform, then twitter. platform?: 'twitter' | 'truth_social' | 'binance_square'; eventId: string; observedAt: number; receivedAt?: number; action: 'pin'; author: TweetAuthor; text?: string; tweet?: TweetContent; }; type TweetUnpinEvent = { tweetId: string; // When absent, use tweet.author.platform or author.platform, then twitter. platform?: 'twitter' | 'truth_social' | 'binance_square'; eventId: string; observedAt: number; receivedAt?: number; action: 'unpin'; author: TweetAuthor; text?: string; tweet?: TweetContent; }; type AccountEventActor = TweetAuthor & { websiteUrl?: string; }; type ProfileUpdateEvent = { kind: 'PROFILE'; eventId: string; observedAt: number; receivedAt?: number; actor: AccountEventActor; changes: { avatar?: string; banner?: string; bio?: string; handle?: string; location?: string; name?: string; verifiedLabel?: TweetVerifiedLabel | null; websiteUrl?: string | null; }; previous?: { avatar?: string; banner?: string; bio?: string; handle?: string; location?: string; name?: string; verifiedLabel?: TweetVerifiedLabel | null; websiteUrl?: string | null; }; }; type FollowEvent = { kind: 'FOLLOW'; eventId: string; observedAt: number; receivedAt?: number; actor: AccountEventActor; target: AccountEventActor & { handle: string; }; }; type UnfollowEvent = { kind: 'UNFOLLOW'; eventId: string; observedAt: number; receivedAt?: number; actor: AccountEventActor; target: AccountEventActor & { handle: string; }; }; type AffiliateAccountIdentity = AccountEventActor & { id: string; }; type AffiliateUpdateEvent = { action: 'added' | 'removed'; eventId: string; observedAt: number; receivedAt?: number; organization: AffiliateAccountIdentity; member: AffiliateAccountIdentity; }; type CalloutCaller = { username: string; image?: string; }; type CalloutReply = { caller: CalloutCaller; replyId: string; parentReplyId?: string; rootReplyId?: string; text?: string; mediaUrl?: string; }; type CalloutEvent = { platform: 'pump_fun'; caller: CalloutCaller; kind?: 'callout' | 'author_update' | 'reply' | 'repost'; text?: string; mediaUrl?: string; // Required for replies and author updates. replyId?: string; parentReplyId?: string; rootReplyId?: string; reference?: { caller: CalloutCaller; text?: string; mediaUrl?: string; reply?: CalloutReply; }; position?: { amountHeld?: string; valueUsd?: string; costBasisUsd?: string; pnlUsd?: string; pnlPercentage?: string; realizedPnlUsd?: string; }; token: { address: string; chainId?: string; symbol?: string; name?: string; image?: string; }; url?: string; marketCapUsd?: number; // SOL, exact decimal. calloutPrice?: string; // USD, exact decimal. calloutPriceUsd?: string; multiple?: number; // SOL peak, exact decimal. maxPriceSol?: string; // USD peak, exact decimal. maxPriceUsd?: string; calloutId: string; createdAt: number; receivedAt?: number; }; type CalloutUpdateEvent = CalloutEvent & { // Original envelope id, not calloutId. updateOf: string; }; type PerpCalloutEvent = { platform: 'pump_fun'; caller: CalloutCaller; // The perpetual market and the original callout's stance. market: { // For example 'hyperliquid'. venue: string; // The venue's market symbol, case kept: 'BTC', 'xyz:CL'. symbol: string; name?: string; image?: string; side: 'long' | 'short'; // Exact decimal multiplier, for example '10' or '2.5'. leverage: string; // USD, exact decimals. entryPriceUsd?: string; closePriceUsd?: string; closedAt?: number; }; kind?: 'callout' | 'author_update' | 'reply' | 'repost'; text?: string; mediaUrl?: string; // Required for replies and author updates. replyId?: string; parentReplyId?: string; rootReplyId?: string; reference?: CalloutEvent['reference']; // The acting account's position snapshot, exact decimals. // market.side is the original callout's stance, not this position's direction. position?: { // Coin units. size?: string; notionalUsd?: string; marginUsd?: string; pnlUsd?: string; // Of margin. pnlPercentage?: string; realizedPnlUsd?: string; }; // USD, exact decimal. calloutPriceUsd?: string; // Return multiple, leverage included. multiple?: number; calloutId: string; createdAt: number; receivedAt?: number; }; type FomoCoin = { address: string; networkId: number; name?: string; symbol?: string; image?: string; metadataObservedAt?: number; priceUsd?: string; marketCapUsd?: string; liquidityUsd?: string; volume24hUsd?: string; change24hPercent?: string; }; type FomoThesisEvent = { platform: 'fomo'; coin: FomoCoin; author: { id: string; username: string; verified: boolean; displayName?: string; avatar?: string; twitter?: string; }; thesis: { id: string; text: string; createdAt: number; likes: number; replies: number; tradeId?: string; parentId?: string; segments?: Array<{ text: string; link?: string }>; }; position?: { tokenAmount?: string; usdValue?: string; unrealizedPnlUsd?: string; realizedPnlUsd?: string; unrealizedPnlPercent?: string; realizedPnlPercent?: string; closedAt?: number; }; observedAt?: number; receivedAt?: number; }; type FomoTokenVerifiedEvent = { platform: 'fomo'; coin: FomoCoin; observedAt: number; receivedAt?: number; }; type CharityAddedEvent = { id: string; name: string; slug: string; enabled: boolean; taxId?: string; location?: { city?: string; state?: string; country?: string; }; observedAt: number; }; type TwitterHandlesResult = { action: 'follow' | 'unfollow'; requestId: string | null; results: Array<{ input: string; state: | 'added' | 'already_following' | 'invalid_input' | 'duplicate' | 'not_found' | 'failed' | 'removed' | 'not_following'; message?: string; }>; error: string | null; }; type NewsSource = { id: string; name: string; }; type NewsMedia = { url: string; type?: 'image' | 'video'; caption?: string; }; type NewsArticle = { source: NewsSource; url: string; title: string; publishedAt: string; receivedAt: number; modifiedAt?: string; primaryCategory?: string; categories: string[]; author?: string; keywords: string[]; description?: string; summary?: string; media: NewsMedia[]; content?: string; language?: string; copyright?: string; }; type EnvelopeBase< TFamily extends 'tweet' | 'account' | 'charity' | 'control' | 'news', TOp extends string, TPayload extends object, > = { v: 1; t: TFamily; op: TOp; id?: string; ts: number; d: TPayload; }; type TweetContentEnvelope = EnvelopeBase<'tweet', 'content', TweetContent>; type TweetMetaEnvelope = EnvelopeBase<'tweet', 'meta', TweetMeta>; type TweetUpdateEnvelope = EnvelopeBase<'tweet', 'update', TweetUpdate>; type TweetDeleteEnvelope = EnvelopeBase<'tweet', 'delete', TweetDeleteEvent>; type TweetPinEnvelope = EnvelopeBase<'tweet', 'pin', TweetPinEvent>; type TweetUnpinEnvelope = EnvelopeBase<'tweet', 'unpin', TweetUnpinEvent>; type AccountProfileEnvelope = EnvelopeBase< 'account', 'profile_update', ProfileUpdateEvent >; type AccountFollowEnvelope = EnvelopeBase<'account', 'follow', FollowEvent>; type AccountUnfollowEnvelope = EnvelopeBase<'account', 'unfollow', UnfollowEvent>; type AccountAffiliateEnvelope = EnvelopeBase< 'account', 'affiliate_update', AffiliateUpdateEvent >; type AccountCalloutEnvelope = EnvelopeBase<'account', 'callout', CalloutEvent> & { id: string; }; type AccountCalloutUpdateEnvelope = EnvelopeBase< 'account', 'callout_update', CalloutUpdateEvent > & { id: string; }; type AccountPerpCalloutEnvelope = EnvelopeBase< 'account', 'perp_callout', PerpCalloutEvent > & { id: string; }; type AccountThesisEnvelope = EnvelopeBase<'account', 'thesis', FomoThesisEvent> & { id: string; }; type AccountTokenVerifiedEnvelope = EnvelopeBase< 'account', 'token_verified', FomoTokenVerifiedEvent > & { id: string; }; type AccountEnvelope = | AccountProfileEnvelope | AccountFollowEnvelope | AccountUnfollowEnvelope | AccountAffiliateEnvelope | AccountCalloutEnvelope | AccountCalloutUpdateEnvelope | AccountPerpCalloutEnvelope | AccountThesisEnvelope | AccountTokenVerifiedEnvelope; type CharityAddedEnvelope = EnvelopeBase<'charity', 'added', CharityAddedEvent> & { id: string; }; type EmptyPayload = Record; type AuthPingCommand = { op: 'auth_ping' }; type AuthPongEnvelope = EnvelopeBase<'control', 'auth_pong', EmptyPayload>; type TwitterHandlesResultEnvelope = EnvelopeBase< 'control', 'twitter_handles_result', TwitterHandlesResult >; type ControlEnvelope = AuthPongEnvelope | TwitterHandlesResultEnvelope; type NewsEnvelope = EnvelopeBase<'news', 'article', NewsArticle> & { id: string; }; type TweetStreamEnvelope = | TweetContentEnvelope | TweetMetaEnvelope | TweetUpdateEnvelope | TweetDeleteEnvelope | TweetPinEnvelope | TweetUnpinEnvelope | AccountEnvelope | CharityAddedEnvelope | NewsEnvelope | ControlEnvelope; // Feed this router only values returned by a complete runtime decoder. // See the reference consumer linked below for the executable decoder. type DecodedEnvelope = | { kind: 'known'; event: TweetStreamEnvelope } | { kind: 'unknown' }; type ProtocolHandlers = { tweetContent: (event: TweetContentEnvelope) => void; tweetMeta: (event: TweetMetaEnvelope) => void; tweetUpdate: (event: TweetUpdateEnvelope) => void; tweetDelete: (event: TweetDeleteEnvelope) => void; tweetPin: (event: TweetPinEnvelope) => void; tweetUnpin: (event: TweetUnpinEnvelope) => void; accountProfileUpdate: (event: AccountProfileEnvelope) => void; accountFollow: (event: AccountFollowEnvelope) => void; accountUnfollow: (event: AccountUnfollowEnvelope) => void; accountAffiliateUpdate: (event: AccountAffiliateEnvelope) => void; accountCallout: (event: AccountCalloutEnvelope) => void; accountCalloutUpdate: (event: AccountCalloutUpdateEnvelope) => void; accountPerpCallout: (event: AccountPerpCalloutEnvelope) => void; accountThesis: (event: AccountThesisEnvelope) => void; accountTokenVerified: (event: AccountTokenVerifiedEnvelope) => void; charityAdded: (event: CharityAddedEnvelope) => void; newsArticle: (event: NewsEnvelope) => void; authPong: (event: AuthPongEnvelope) => void; twitterHandlesResult: (event: TwitterHandlesResultEnvelope) => void; // Count and discard unknown input without logging its raw payload. unknown: () => void; }; function assertNever(value: never): never { throw new Error('Unhandled validated envelope'); } function route(decoded: DecodedEnvelope, handlers: ProtocolHandlers): void { if (decoded.kind === 'unknown') { handlers.unknown(); return; } const event = decoded.event; switch (event.t) { case 'tweet': switch (event.op) { case 'content': handlers.tweetContent(event); return; case 'meta': handlers.tweetMeta(event); return; case 'update': handlers.tweetUpdate(event); return; case 'delete': handlers.tweetDelete(event); return; case 'pin': handlers.tweetPin(event); return; case 'unpin': handlers.tweetUnpin(event); return; default: return assertNever(event); } case 'account': switch (event.op) { case 'profile_update': handlers.accountProfileUpdate(event); return; case 'follow': handlers.accountFollow(event); return; case 'unfollow': handlers.accountUnfollow(event); return; case 'affiliate_update': handlers.accountAffiliateUpdate(event); return; case 'callout': handlers.accountCallout(event); return; case 'callout_update': handlers.accountCalloutUpdate(event); return; case 'perp_callout': handlers.accountPerpCallout(event); return; case 'thesis': handlers.accountThesis(event); return; case 'token_verified': handlers.accountTokenVerified(event); return; default: return assertNever(event); } case 'charity': handlers.charityAdded(event); return; case 'news': handlers.newsArticle(event); return; case 'control': switch (event.op) { case 'auth_pong': handlers.authPong(event); return; case 'twitter_handles_result': handlers.twitterHandlesResult(event); return; default: return assertNever(event); } default: return assertNever(event); } } ``` ### Prepare for production - Reconnect with backoff after close or network error. - Connect only to the documented TweetStream endpoints and use the authentication methods above. TweetStream handles routing; no infrastructure-specific headers are required. - Use `(platform, tweetId)` as the post key, not the envelope id. Read `platform` from `author.platform` on content and `d.platform` on later operations. - On older operations without `d.platform`, use an included author platform or default to `twitter`. - Apply every `tweet/update` idempotently. If it includes `ref`, replace the stored reference with that snapshot and follow `ref.subtweet` for the next referenced post. - Fingerprint the full envelope before dropping an exact replay. - Treat `meta` as late-arriving enrichment for a tweet you may already have routed. - Store receipts and projections in indexed durable storage. Define a retention or archival policy for your replay window and storage budget; never remove pending work. - Log failed actions without payload data and retry them with backoff. Keep the same receipt ID as the idempotency key. - Track active WebSocket connection count against your plan limit. ### Measure signal latency Record local receipt time at the start of the message callback. For X/Twitter events, decode the tweet snowflake timestamp to measure publication to receipt. Keep the host clock synced with NTP for meaningful wall-clock results. Use a monotonic clock for processing segments after receipt. - Report the watchlist, consumer region, UTC test window, sample size, p50, and p95. - Record reconnects, missing events, clock-sync status, and every exclusion rule. - Report cold-start and post-reconnect samples separately instead of folding them into warm-path results. - Compare results only when publication point, receipt point, geography, sample, and percentile use the same boundary. | Segment | Start | Stop | | --- | --- | --- | | Publication to receipt | X snowflake timestamp | Local time captured at the top of the socket callback | | Receipt to decision | Local socket receipt | Strategy and risk decision ready | | Decision to venue acknowledgement | Risk-approved decision | Separate venue response or rejection | #### Measure snowflake latency ```typescript type ContentEvent = { t?: string; op?: string; d?: { tweetId?: string; }; }; const TWITTER_EPOCH_MS = 1_288_834_974_657n; function tweetIdToTimestampMs(tweetId: string) { const id = BigInt(tweetId); return Number((id >> 22n) + TWITTER_EPOCH_MS); } function measureSnowflakeLatency(tweetId: string, arrivedAtMs: number) { const tweetedAtMs = tweetIdToTimestampMs(tweetId); return arrivedAtMs - tweetedAtMs; } ws.on("message", (raw) => { const arrivedAtMs = Date.now(); const event = JSON.parse(raw.toString()) as ContentEvent; const tweetId = event.d?.tweetId; if (event.t === "tweet" && event.op === "content" && tweetId) { const latencyMs = measureSnowflakeLatency(tweetId, arrivedAtMs); console.log("publication-to-receipt ms", latencyMs); } }); ``` ### Build the reference consumer When you build your own consumer, these pages cover each part. Start with the router above, then add one reconnecting client, durable recovery, and account management. - [Route every operation](https://tweetstream.io/docs/production-consumer#complete-router): Typed handlers for all 19 server operations. - [Reconnect with Node.js](https://tweetstream.io/docs/connection-auth-heartbeat#connect): Classify upgrade failures and reconnect with backoff. - [Reconnect with Python](https://tweetstream.io/docs/connection-auth-heartbeat#python): Run the same connection loop with Python. - [Recover with History](https://tweetstream.io/docs/envelope-delivery-recovery-errors#backfill): Replay stored pages with an opaque cursor. - [Query History](https://tweetstream.io/docs/history-api#request): Set a bounded window and fixed filters. - [Manage accounts](https://tweetstream.io/docs/account-management#add-remove): Add and remove monitored Twitter handles. ## Connection, authentication, and heartbeat Use the documented regional endpoint, authenticate during the upgrade, and leave native ping and pong handling enabled. Canonical URL: https://tweetstream.io/docs/connection-auth-heartbeat ### Choose a base URL | Surface | URL | Use | | --- | --- | --- | | WebSocket (USA) | `wss://ws-iad.tweetstream.io/ws` | Use for connections in the USA | | WebSocket (global) | `wss://ws-global.tweetstream.io/ws` | Use for connections outside the USA | | REST | `https://api.tweetstream.io` | Base origin for `/api/history`, `/api/me`, and account management | | Dashboard | `https://tweetstream.io/dashboard` | API key, watchlists, billing, and Discord routing | ### Authenticate requests Authenticate realtime clients with WebSocket subprotocols and REST requests with a bearer token. Keep API keys on the server, never in public browser code. | Context | Header or protocol | Notes | | --- | --- | --- | | WebSocket | `tweetstream.v1` + `tweetstream.auth.token.` | Preferred realtime authentication | | WebSocket fallback | `Authorization: Bearer ` or `?apiKey=` | Prefer Authorization; use query authentication only when the runtime cannot set headers | | REST | `Authorization: Bearer ` | History accepts a standard key for Pro or Scale. An active base plan with current Ultra can use its standard key for full History, while a current Ultra key can request full History for its selected accounts. Account management and `/api/me` accept either key | #### Authenticate a server connection ```typescript const socket = new WebSocket("wss://ws-global.tweetstream.io/ws", [ "tweetstream.v1", `tweetstream.auth.token.${process.env.TWEETSTREAM_API_KEY}`, ]); socket.addEventListener("message", (event) => { const message = JSON.parse(event.data); console.log(message.t, message.op, message.d); }); ``` ### Connect with Node.js Use `wss://ws-iad.tweetstream.io/ws` in the USA and `wss://ws-global.tweetstream.io/ws` elsewhere. The server responds with `tweetstream.v1`; it does not echo the authentication-token protocol. The example reconnects with exponential backoff. Short sessions keep increasing the delay; 30 seconds of uptime resets it. #### Node.js reconnecting consumer ```typescript import WebSocket from "ws"; type StreamEvent = { t?: string; op?: string; d?: { author?: { handle?: string }; detected?: unknown; text?: string; }; }; const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) { throw new Error("Missing TWEETSTREAM_API_KEY"); } let retry = 0; let healthyTimer: ReturnType | undefined; let reconnectTimer: ReturnType | undefined; function scheduleReconnect(reason: string) { if (reconnectTimer) return; const backoffMs = Math.min(30_000, 1_000 * 2 ** retry); const jitterMs = Math.floor(Math.random() * 500); const delayMs = backoffMs + jitterMs; retry += 1; console.warn(`Reconnecting in ${delayMs}ms: ${reason}`); reconnectTimer = setTimeout(() => { reconnectTimer = undefined; connect(); }, delayMs); } function connect() { const ws = new WebSocket("wss://ws-global.tweetstream.io/ws", [ "tweetstream.v1", `tweetstream.auth.token.${apiKey}`, ]); ws.on("open", () => { if (reconnectTimer) clearTimeout(reconnectTimer); reconnectTimer = undefined; healthyTimer = setTimeout(() => { retry = 0; healthyTimer = undefined; }, 30_000); console.log("TweetStream connected"); }); ws.on("message", (raw) => { const event = JSON.parse(raw.toString()) as StreamEvent; if (event.t === "tweet" && event.op === "content") { const tweet = event.d; console.log(tweet?.author?.handle, tweet?.text); } if (event.t === "tweet" && event.op === "meta") { console.log("enrichment", event.d?.detected); } }); ws.on("close", (code, reason) => { if (healthyTimer) clearTimeout(healthyTimer); healthyTimer = undefined; scheduleReconnect(`close ${code}: ${reason.toString()}`); }); ws.on("unexpected-response", (_request, response) => { console.error( "Connection rejected", response.statusCode, response.statusMessage, ); response.resume(); if (response.statusCode === 429 || response.statusCode === 503) { scheduleReconnect(`HTTP ${response.statusCode}`); return; } process.exitCode = 1; }); ws.on("error", (error) => { console.error("WebSocket error", error.message); }); } connect(); ``` ### Connect with Python Use any WebSocket runtime that can send both subprotocols. Clean closes and transport errors reconnect with exponential backoff. Short sessions keep increasing the delay; 30 seconds of uptime resets it. #### Python reconnecting consumer ```python import asyncio import json import os import websockets API_KEY = os.environ["TWEETSTREAM_API_KEY"] URI = "wss://ws-global.tweetstream.io/ws" PROTOCOLS = ["tweetstream.v1", f"tweetstream.auth.token.{API_KEY}"] async def main(): loop = asyncio.get_running_loop() retry = 0 while True: connected_at = None reason = "connection closed" try: async with websockets.connect(URI, subprotocols=PROTOCOLS) as ws: connected_at = loop.time() async for raw in ws: event = json.loads(raw) if event["t"] == "tweet" and event["op"] == "content": tweet = event["d"] handle = tweet.get("author", {}).get("handle") print(handle, tweet.get("text")) except Exception as error: reason = str(error) if connected_at is not None and loop.time() - connected_at >= 30: retry = 0 wait = min(30, 2 ** retry) retry = min(retry + 1, 5) print(f"reconnecting in {wait}s after {reason}") await asyncio.sleep(wait) asyncio.run(main()) ``` ### Handle heartbeats and disconnects TweetStream sends a native WebSocket ping every 30 seconds. Standard Node and Python clients reply with pong automatically. The server closes an unresponsive socket. Reconnect, then use History API to backfill stored content, profile, follow, and affiliate events. ### Handle limits and retries Your plan sets active WebSocket, monitored-account, and History API limits. Handle add and remove requests share one limit across all your API keys and connections. You can send 100 requests in a burst, then 1 per second. A request with more than 100 handles counts once for every 100 handles, rounded up. On `429`, pause that workflow and wait for `retryAfterSeconds` or the `Retry-After` header when present. Otherwise, use your normal backoff. | Surface | Limit signal | Recommended handling | | --- | --- | --- | | WebSocket | 429 during upgrade | Close unused sockets or move to a plan with more connections | | History API | `retryAfterSeconds` when rate limited | Wait before replaying the next window | | Tracked accounts | Plan usage from `/api/me` | Check count and limit before batch add flows | | Handle requests | `429`, or the limit `error` in `twitter_handles_result` | Batch changed handles, up to 100 per request, then back off before retrying | ## Envelope, delivery, recovery, and errors Route the v1 envelope by family and operation, tolerate duplicates, and use stored history when a replay window is available. Canonical URL: https://tweetstream.io/docs/envelope-delivery-recovery-errors ### Route the envelope Route every realtime envelope first by `t`, then by `op`. Keep handlers idempotent because history replay can return events already processed live. - [Open the complete router](https://tweetstream.io/docs/production-consumer#complete-router): Every payload type and an exhaustive `switch` over all server operations. #### Envelope base type ```typescript type EnvelopeBase< TFamily extends 'tweet' | 'account' | 'charity' | 'control' | 'news', TOp extends string, TPayload extends object, > = { v: 1; t: TFamily; op: TOp; id?: string; ts: number; d: TPayload; }; ``` ### Route operations TweetStream sends 19 server operations. Route each envelope by `t`, then `op`, and ignore unknown operations without closing the socket. Ignore payload fields you don't recognize. Clients send two commands: `auth_ping` for an authentication check, and `twitter_handles` to add or remove accounts on a handle-management socket. | Family | Operation | Meaning | | --- | --- | --- | | `tweet` | `content` | Post content | | `tweet` | `meta` | Post enrichment | | `tweet` | `update` | Post update | | `tweet` | `delete` | Post deletion | | `tweet` | `pin` | Post pinned | | `tweet` | `unpin` | Post unpinned | | `account` | `profile_update` | Profile update | | `account` | `follow` | Account followed | | `account` | `unfollow` | Account unfollowed | | `account` | `affiliate_update` | Affiliate membership update | | `account` | `callout` | Token callout | | `account` | `callout_update` | Callout enrichment | | `account` | `perp_callout` | Perpetual callout | | `account` | `thesis` | FOMO thesis | | `account` | `token_verified` | FOMO token verification observed | | `charity` | `added` | Charity added | | `news` | `article` | News article | | `control` | `auth_pong` | Authentication pong | | `control` | `twitter_handles_result` | Handle command result | ### Treat delivery as an event stream The envelope has no acknowledgement, resume token, or sequence number. Do not infer ordering or exactly-once delivery from `ts` or `id`. Make handlers idempotent and keep enough local state to recognize events your application has already applied. ### Backfill after reconnect Choose a bounded `startDate` and `endDate`, follow `nextCursor` to null without changing the other filters, and process every returned row idempotently. Persist the window and cursor together if an interrupted replay must resume rather than restart. History returns stored events; it does not promise completeness or a retention duration. `AFFILIATE` returns stored affiliate changes, not a current-list snapshot. Delete, pin, and unpin remain live-only events. #### Replay a recovery window ```typescript type HistoryRow = { time: string; tweetId: string; }; type HistoryPage = { data: Array; metadata: { nextCursor: string | null }; }; async function replayAfterReconnect( checkpoint: string, processEvent: (event: HistoryRow) => Promise, saveCheckpoint: (eventTime: string) => Promise, ) { const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY"); const url = new URL("https://api.tweetstream.io/api/history"); const replayEnd = new Date().toISOString(); url.searchParams.set("handles", "marketdesk"); url.searchParams.set("startDate", checkpoint); url.searchParams.set("endDate", replayEnd); url.searchParams.set("limit", "1000"); url.searchParams.set("type", "TWEET"); const pages: Array> = []; let cursor: string | null = null; do { if (cursor) url.searchParams.set("cursor", cursor); const response = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` }, }); if (!response.ok) { const detail = await response.text(); throw new Error(`Replay failed (${response.status}): ${detail}`); } const page = (await response.json()) as HistoryPage; pages.push(page.data); cursor = page.metadata.nextCursor; } while (cursor); for (const event of pages.reverse().flatMap((page) => [...page].reverse())) { await processEvent(event); } await saveCheckpoint(replayEnd); } ``` ### Fix handshake errors A failed WebSocket upgrade returns JSON before the socket is accepted. The client can safely log the response. | Status | Likely cause | Fix | | --- | --- | --- | | `400` | Missing or invalid WebSocket protocol headers | Send `tweetstream.v1` and a valid auth token protocol | | `401` | Missing, empty, or invalid API key | Regenerate or rotate the API key from the dashboard | | `403` | Subscription state does not allow live streaming | Start a trial, renew, or upgrade the account | | `429` | Active WebSocket connection limit reached | Close an old socket or move to a higher plan | | `503` | Connection limit service temporarily unavailable | Retry with backoff | #### Read an upgrade denial ```json { "error": "WebSocket connection limit reached (3/3 active). Close an existing connection and retry.", "status": 429 } ``` ## Event reference Find an event family, then open its full payload and integration guide. Canonical URL: https://tweetstream.io/docs/payloads-detections-ocr ### Tweet content Use `tweet/content` as the first usable post, then branch on `author.platform`. - [Open social content](https://tweetstream.io/docs/social-content): Compare Twitter, Truth Social, and Binance Square payloads. #### Route by platform Read the post key from `(author.platform, tweetId)`. If `platform` is absent, use `twitter`. #### Read references Keep referenced posts and their attachments under `ref`. A nested reference may carry only `author` until a later update adds its `tweetId`. ### Enrichment metadata Replace the metadata at `(platform, tweetId)` with each `tweet/meta` snapshot. Do not keep fields missing from the new snapshot. - [Open tweet/meta](https://tweetstream.io/docs/tweet-updates-lifecycle#meta): Read detection, OCR, token, exchange, and market fields. ### Tweet updates Patch only fields present in `tweet/update`; do not replace the whole post. - [Open tweet/update](https://tweetstream.io/docs/tweet-updates-lifecycle#update): Apply text completion, references, media, polls, and articles. #### Match the post Match every update with `(platform, tweetId)`. #### Replace reference snapshots If an update contains `ref`, replace the stored reference with that snapshot. #### Complete optional fields Treat present poll, article, and media values as complete replacements for those fields. ### Tweet lifecycle Apply delete, pin, and unpin to the stored post without overwriting its content. - [Open lifecycle events](https://tweetstream.io/docs/tweet-updates-lifecycle#lifecycle-events): Copy the exact delete, pin, and unpin payloads. ### Account events Route profile, follow, unfollow, and affiliate changes under the `account` family. - [Open account events](https://tweetstream.io/docs/profile-follow-affiliate): Copy every account event and its storage key. #### Route account operations Branch on `op`; ignore unknown operations without closing the socket. #### Store affiliate relationships Apply the action to `(organization.id, member.id)` and use `eventId` only for an exact replay. #### Replay stored changes Use `type=PROFILE`, `FOLLOW`, or `AFFILIATE` with the History API. ### Callouts Selected accounts emit structured `account/callout` events on the same WebSocket. - [Open callout events](https://tweetstream.io/docs/callouts): Configure accounts and consume caller, token, price, and timestamp fields. #### Select accounts Add a pump.fun username, Solana wallet, or profile URL in the Callouts tab. #### Route the event Alert on `account/callout`, then merge the `account/callout_update` that usually follows within a few seconds. Read the caller and token address before optional fields. #### Use identifiers Deduplicate by envelope `id`. Merge enrichment into `d.updateOf`, including nested fields, without another alert. ### Charity events Enabled charity alerts emit live-only `charity/added` events. - [Open charity events](https://tweetstream.io/docs/charity): Copy the full event and its optional location fields. ### News articles Enabled publications emit `news/article`; stored articles use the separate News History API. - [Open news events and history](https://tweetstream.io/docs/news): Select publications, consume articles, and continue with `nextCursor`. #### Select publications Read and update the enabled publication set before filtering live events. #### Read live articles Use the envelope `id` for idempotency and keep `source.id` with the article. #### Page through history Pass `nextCursor` back unchanged until it is null. ### Event sequence Use an idempotent local projection; the WebSocket envelope does not contain a sequence number. #### Receive content Store the first usable content event. #### Replace enrichment Replace each live metadata snapshot by post key. #### Apply lifecycle Apply lifecycle operations to the same post. ### Control messages Use `auth_pong` for connection state and `twitter_handles_result` for command outcomes. - [Open control messages](https://tweetstream.io/docs/control): Copy auth and handle-management messages. ### Handle management channel Follow or unfollow monitored Twitter handles over the handle-management WebSocket or REST API. - [Read command results](https://tweetstream.io/docs/control#twitter-handles-result): Handle partial, idempotent, and failed rows. - [Manage accounts with REST](https://tweetstream.io/docs/account-management): Add, remove, inspect, and configure monitored accounts. ## Social content events Social content uses `tweet/content`; select the platform from `author.platform` before applying platform-specific fields. Canonical URL: https://tweetstream.io/docs/social-content ### tweet/content Route a content event by `t="tweet"` and `op="content"`, then key the post by `(author.platform, tweetId)`. #### Tweet content type ```typescript type VerifiedType = 'blue' | 'business' | 'government' | 'verified' | 'none'; type TweetVerifiedLabel = { badge: string | null; description: string; url: string | null; }; type TweetAuthor = { banner?: string; bio?: string; followersCount?: number; followingCount?: number; id?: string; joinedAt?: number; location?: string; metrics?: { likes?: number; tweets?: number; }; // Includes a leading @ when present, for example "@elonmusk". handle?: string; name?: string; platform?: 'twitter' | 'truth_social' | 'binance_square'; profileImage?: string; // The account's own website, when it has one. url?: string; verifiedLabel?: TweetVerifiedLabel; verifiedType?: VerifiedType; }; type Media = { url: string; } & ( | { type: 'video'; // Every video is a progressive MP4. A public still poster is included // when available. thumbnail?: string; } | { type?: 'image' | 'gif'; thumbnail?: string; } ); type TweetUrl = { url: string; name?: string; tco?: string; }; type TweetMention = { handle?: string; id?: string; name?: string; }; type TweetArticle = { description?: string; id?: string; publishedAt?: number; text?: string; thumbnail?: string; title: string; updatedAt?: number; url: string; }; type TweetPollChoice = { id?: string; image?: string; label: string; votes?: number; }; type TweetPoll = { choices: TweetPollChoice[]; endsAt?: number; totalVotes?: number; updatedAt?: number; }; type TweetContentKind = 'post' | 'reply' | 'quote' | 'retweet'; type TweetReference = { article?: TweetArticle; type: 'reply' | 'quote' | 'retweet'; // Absent until known: a partial ref has only author; a later tweet/update completes it. tweetId?: string; text?: string; translatedText?: string; author?: TweetAuthor; media?: Media[]; poll?: TweetPoll; quoted?: TweetReference; subtweet?: TweetReference; }; type TweetContent = { tweetId: string; kind: TweetContentKind; // Original tweet text when the event includes both original and translated text. text: string; // Translation, present only when available. translatedText?: string; createdAt: number; author: TweetAuthor; article?: TweetArticle; link?: string; media?: Media[]; mentions?: TweetMention[]; poll?: TweetPoll; receivedAt?: number; urls?: TweetUrl[]; ref?: TweetReference; // The post a reply also quotes. A quote keeps the post it quotes in ref. quoted?: TweetReference; }; ``` #### Tweet content event ```json { "v": 1, "t": "tweet", "op": "content", "id": "1234567890", "ts": 1702500000130, "d": { "tweetId": "1234567890", "kind": "reply", "text": "Could this launch today?", "createdAt": 1702500000000, "author": { "handle": "@marketdesk", "platform": "twitter" } } } ``` #### Reply that quotes ```json { "v": 1, "t": "tweet", "op": "content", "id": "1234567891", "ts": 1702500000330, "d": { "tweetId": "1234567891", "text": "Same team, same plan:", "createdAt": 1702500000200, "kind": "reply", "ref": { "type": "reply", "tweetId": "1234567880", "text": "Mainnet is ready for launch.", "author": { "handle": "@projectteam" } }, "quoted": { "type": "quote", "author": { "handle": "@projectteam" } }, "author": { "handle": "@marketdesk", "platform": "twitter" } } } ``` ### Twitter Twitter content can be a post, reply, quote, or retweet. References and media are included when available. ### Truth Social Truth Social is opt-in live delivery for Donald Trump (`@realDonaldTrump`) and the White House (`@WhiteHouse`). Configure it from the Accounts tab in the dashboard when your account is eligible. Content uses the tweet envelope with `author.platform="truth_social"` and can be a post, reply, quote, or retweet. Metadata, updates, delete, and pin events can appear when observed. Do not use general account management to add arbitrary Truth Social handles, and do not expect History replay. #### Truth Social content event ```json { "v": 1, "t": "tweet", "op": "content", "id": "tweet-content", "ts": 1772000001060, "d": { "tweetId": "tweet-content", "text": "hello", "createdAt": 1772000001000, "receivedAt": 1772000001050, "kind": "post", "author": { "id": "truth-author", "handle": "@realDonaldTrump", "name": "Donald J. Trump", "platform": "truth_social" } } } ``` ### Binance Square Enabled catalog accounts use `author.platform="binance_square"`. Content is live-only and does not consume a monitored Twitter account slot. #### Binance Square content event ```json { "v": 1, "t": "tweet", "op": "content", "id": "square-content", "ts": 1772000001060, "d": { "tweetId": "square-content", "text": "Weekly market outlook is live.", "createdAt": 1772000001000, "receivedAt": 1772000001050, "kind": "post", "author": { "id": "square-author", "handle": "@marketresearch", "name": "Market Research", "platform": "binance_square" } } } ``` ### References and media Read the referenced post from `d.ref`. Its author or media may arrive before `text`. References can arrive in later `tweet/update` frames or remain incomplete. Treat each nested reference as its own post. `d.quoted` is the post this post quotes. It appears on a reply that also quotes a post. A quote post keeps the post it quotes in `ref` and has no `quoted`. `quoted` can start with only `author` or `tweetId`, and a later `tweet/update` completes it. A nested reference can carry `subtweet` (the post it replies to, reposts, or quotes) and `quoted` (the post it quotes). When a referenced post is a quote, the post it quotes is either a `subtweet` typed `quote` or a `quoted` with no `subtweet`. A reply's parent that quotes a post can arrive as a `ref` typed `reply` that carries `quoted` and no `subtweet`. ## Tweet metadata, updates, and lifecycle Replace live metadata snapshots and merge updates by `(platform, tweetId)`, then apply lifecycle operations without replacing stored content. Canonical URL: https://tweetstream.io/docs/tweet-updates-lifecycle ### tweet/meta A live metadata payload is the latest snapshot for its post. Replace the previous metadata so omitted fields are cleared. History returns the stored enrichment attached to its row. During recovery, use it only when local metadata is empty; do not overwrite a live snapshot. #### Tweet metadata type ```typescript type TweetMeta = { tweetId: string; // Pair with tweetId when merging enrichment. When omitted, use twitter. platform?: 'twitter' | 'truth_social' | 'binance_square'; ocr?: { text: string; }; detected?: { tokens?: Array<{ symbol?: string; name?: string; contract?: string; chain?: string; networkId?: number; priceUsd?: number; sources: Array<'text' | 'ocr'>; }>; cex?: Array<{ exchange: 'bybit' | 'binance' | 'hyperliquid'; symbol?: string; priceUsd?: number; url?: string; baseAsset?: string; quoteAsset?: string; sources: Array<'text' | 'ocr'>; }>; prediction?: Array<{ exchange: 'polymarket' | 'kalshi'; marketId?: string; title?: string; priceUsd?: number; url?: string; sources: Array<'text' | 'ocr'>; }>; }; }; ``` #### Tweet metadata event ```json { "v": 1, "t": "tweet", "op": "meta", "id": "1234567890", "ts": 1702500001000, "d": { "tweetId": "1234567890", "platform": "twitter", "ocr": { "text": "Chart showing SOL breakout at $100" }, "detected": { "tokens": [ { "symbol": "SOL", "name": "Solana", "priceUsd": 98.50, "sources": ["text", "ocr"] } ] } } } ``` ### tweet/update Apply every update by `(platform, tweetId)`. Keep absent fields; replace an included `ref` or `quoted` snapshot. Reprocess the updated post. #### Tweet update type ```typescript type VerifiedType = 'blue' | 'business' | 'government' | 'verified' | 'none'; type TweetVerifiedLabel = { badge: string | null; description: string; url: string | null; }; type TweetAuthor = { banner?: string; bio?: string; followersCount?: number; followingCount?: number; id?: string; joinedAt?: number; location?: string; metrics?: { likes?: number; tweets?: number; }; // Includes a leading @ when present, for example "@elonmusk". handle?: string; name?: string; platform?: 'twitter' | 'truth_social' | 'binance_square'; profileImage?: string; // The account's own website, when it has one. url?: string; verifiedLabel?: TweetVerifiedLabel; verifiedType?: VerifiedType; }; type Media = { url: string; } & ( | { type: 'video'; // Every video is a progressive MP4. A public still poster is included // when available. thumbnail?: string; } | { type?: 'image' | 'gif'; thumbnail?: string; } ); type TweetUrl = { url: string; name?: string; tco?: string; }; type TweetMention = { handle?: string; id?: string; name?: string; }; type TweetArticle = { description?: string; id?: string; publishedAt?: number; text?: string; thumbnail?: string; title: string; updatedAt?: number; url: string; }; type TweetPollChoice = { id?: string; image?: string; label: string; votes?: number; }; type TweetPoll = { choices: TweetPollChoice[]; endsAt?: number; totalVotes?: number; updatedAt?: number; }; type TweetContentKind = 'post' | 'reply' | 'quote' | 'retweet'; type TweetReference = { article?: TweetArticle; type: 'reply' | 'quote' | 'retweet'; // Absent until known: a partial ref has only author; a later tweet/update completes it. tweetId?: string; text?: string; translatedText?: string; author?: TweetAuthor; media?: Media[]; poll?: TweetPoll; quoted?: TweetReference; subtweet?: TweetReference; }; type TweetContent = { tweetId: string; kind: TweetContentKind; // Original tweet text when the event includes both original and translated text. text: string; // Translation, present only when available. translatedText?: string; createdAt: number; author: TweetAuthor; article?: TweetArticle; link?: string; media?: Media[]; mentions?: TweetMention[]; poll?: TweetPoll; receivedAt?: number; urls?: TweetUrl[]; ref?: TweetReference; // The post a reply also quotes. A quote keeps the post it quotes in ref. quoted?: TweetReference; }; type TweetUpdate = { tweetId: string; // Pair with tweetId. When absent, use author.platform, then twitter. platform?: 'twitter' | 'truth_social' | 'binance_square'; article?: TweetArticle; kind?: TweetContentKind; translatedText?: string; author?: TweetAuthor; media?: Media[]; mentions?: TweetMention[]; poll?: TweetPoll; receivedAt?: number; urls?: TweetUrl[]; ref?: TweetReference; quoted?: TweetReference; } & ( | { text?: string; textUpdateType?: never; } | { text: string; // Supplies the full text of a previously shortened post. Not an edit. textUpdateType: 'completion'; } ); ``` #### Tweet update event ```json { "v": 1, "t": "tweet", "op": "update", "id": "1234567890", "ts": 1702500000180, "d": { "tweetId": "1234567890", "platform": "twitter", "ref": { "type": "reply", "tweetId": "1234567880", "text": "Mainnet is ready for launch." } } } ``` #### Recursive reference update ```json { "v": 1, "t": "tweet", "op": "update", "id": "1234567890", "ts": 1702500000240, "d": { "tweetId": "1234567890", "platform": "twitter", "ref": { "type": "reply", "tweetId": "1234567880", "text": "Mainnet is ready for launch.", "author": { "handle": "@projectteam", "name": "Project Team" }, "subtweet": { "type": "quote", "tweetId": "1234567800", "text": "Launch proposal and contract details.", "author": { "handle": "@projectteam", "name": "Project Team" } } } } } ``` ### Lifecycle events Lifecycle operations update a known post and do not replace its stored content. #### Tweet lifecycle types ```typescript type VerifiedType = 'blue' | 'business' | 'government' | 'verified' | 'none'; type TweetVerifiedLabel = { badge: string | null; description: string; url: string | null; }; type TweetAuthor = { banner?: string; bio?: string; followersCount?: number; followingCount?: number; id?: string; joinedAt?: number; location?: string; metrics?: { likes?: number; tweets?: number; }; // Includes a leading @ when present, for example "@elonmusk". handle?: string; name?: string; platform?: 'twitter' | 'truth_social' | 'binance_square'; profileImage?: string; // The account's own website, when it has one. url?: string; verifiedLabel?: TweetVerifiedLabel; verifiedType?: VerifiedType; }; type Media = { url: string; } & ( | { type: 'video'; // Every video is a progressive MP4. A public still poster is included // when available. thumbnail?: string; } | { type?: 'image' | 'gif'; thumbnail?: string; } ); type TweetUrl = { url: string; name?: string; tco?: string; }; type TweetMention = { handle?: string; id?: string; name?: string; }; type TweetArticle = { description?: string; id?: string; publishedAt?: number; text?: string; thumbnail?: string; title: string; updatedAt?: number; url: string; }; type TweetPollChoice = { id?: string; image?: string; label: string; votes?: number; }; type TweetPoll = { choices: TweetPollChoice[]; endsAt?: number; totalVotes?: number; updatedAt?: number; }; type TweetContentKind = 'post' | 'reply' | 'quote' | 'retweet'; type TweetReference = { article?: TweetArticle; type: 'reply' | 'quote' | 'retweet'; // Absent until known: a partial ref has only author; a later tweet/update completes it. tweetId?: string; text?: string; translatedText?: string; author?: TweetAuthor; media?: Media[]; poll?: TweetPoll; quoted?: TweetReference; subtweet?: TweetReference; }; type TweetContent = { tweetId: string; kind: TweetContentKind; // Original tweet text when the event includes both original and translated text. text: string; // Translation, present only when available. translatedText?: string; createdAt: number; author: TweetAuthor; article?: TweetArticle; link?: string; media?: Media[]; mentions?: TweetMention[]; poll?: TweetPoll; receivedAt?: number; urls?: TweetUrl[]; ref?: TweetReference; // The post a reply also quotes. A quote keeps the post it quotes in ref. quoted?: TweetReference; }; type TweetDeleteEvent = { tweetId: string; // When absent, use author.platform, then twitter. platform?: 'twitter' | 'truth_social' | 'binance_square'; eventId?: string; deletedAt?: number; receivedAt?: number; author?: TweetAuthor; text?: string; }; type TweetPinEvent = { tweetId: string; // When absent, use tweet.author.platform or author.platform, then twitter. platform?: 'twitter' | 'truth_social' | 'binance_square'; eventId: string; observedAt: number; receivedAt?: number; action: 'pin'; author: TweetAuthor; text?: string; tweet?: TweetContent; }; type TweetUnpinEvent = { tweetId: string; // When absent, use tweet.author.platform or author.platform, then twitter. platform?: 'twitter' | 'truth_social' | 'binance_square'; eventId: string; observedAt: number; receivedAt?: number; action: 'unpin'; author: TweetAuthor; text?: string; tweet?: TweetContent; }; ``` #### tweet/delete Mark the post deleted when this event is observed. ##### Tweet delete event ```json { "v": 1, "t": "tweet", "op": "delete", "id": "tweet-delete", "ts": 1772000001060, "d": { "eventId": "delete.29043b5a1a4415618c95", "tweetId": "tweet-delete", "platform": "twitter", "author": { "id": "10228272", "handle": "@TeamYouTube" }, "deletedAt": 1772000001050, "receivedAt": 1772000001050, "text": "deleted" } } ``` #### tweet/pin Mark the post pinned and retain any included post snapshot. ##### Tweet pin event ```json { "v": 1, "t": "tweet", "op": "pin", "id": "tweet-pin", "ts": 1772000001060, "d": { "action": "pin", "author": { "id": "10228272", "handle": "@TeamYouTube" }, "eventId": "pin.ab70542b9aa6bec229ef", "observedAt": 1772000001050, "tweetId": "tweet-pin", "platform": "twitter", "receivedAt": 1772000001050, "text": "pinned" } } ``` #### tweet/unpin Remove the pinned state for the identified post. ##### Tweet unpin event ```json { "v": 1, "t": "tweet", "op": "unpin", "id": "tweet-unpin", "ts": 1772000001060, "d": { "action": "unpin", "author": { "id": "10228272", "handle": "@TeamYouTube" }, "eventId": "unpin.0bef09a9f46866cd26d7", "observedAt": 1772000001050, "tweetId": "tweet-unpin", "platform": "twitter", "receivedAt": 1772000001050, "text": "unpinned" } } ``` ## Profile, follow, and affiliate events Account events carry observed profile, follow, and affiliate relationship changes. Canonical URL: https://tweetstream.io/docs/profile-follow-affiliate ### Account event types Route by `op`. Ignore unknown account operations without closing the socket. #### Account event contracts ```typescript type VerifiedType = 'blue' | 'business' | 'government' | 'verified' | 'none'; type TweetVerifiedLabel = { badge: string | null; description: string; url: string | null; }; type TweetAuthor = { banner?: string; bio?: string; followersCount?: number; followingCount?: number; id?: string; joinedAt?: number; location?: string; metrics?: { likes?: number; tweets?: number; }; // Includes a leading @ when present, for example "@elonmusk". handle?: string; name?: string; platform?: 'twitter' | 'truth_social' | 'binance_square'; profileImage?: string; // The account's own website, when it has one. url?: string; verifiedLabel?: TweetVerifiedLabel; verifiedType?: VerifiedType; }; type AccountEventActor = TweetAuthor & { websiteUrl?: string; }; type ProfileUpdateEvent = { kind: 'PROFILE'; eventId: string; observedAt: number; receivedAt?: number; actor: AccountEventActor; changes: { avatar?: string; banner?: string; bio?: string; handle?: string; location?: string; name?: string; verifiedLabel?: TweetVerifiedLabel | null; websiteUrl?: string | null; }; previous?: { avatar?: string; banner?: string; bio?: string; handle?: string; location?: string; name?: string; verifiedLabel?: TweetVerifiedLabel | null; websiteUrl?: string | null; }; }; type FollowEvent = { kind: 'FOLLOW'; eventId: string; observedAt: number; receivedAt?: number; actor: AccountEventActor; target: AccountEventActor & { handle: string; }; }; type UnfollowEvent = { kind: 'UNFOLLOW'; eventId: string; observedAt: number; receivedAt?: number; actor: AccountEventActor; target: AccountEventActor & { handle: string; }; }; type AffiliateAccountIdentity = AccountEventActor & { id: string; }; type AffiliateUpdateEvent = { action: 'added' | 'removed'; eventId: string; observedAt: number; receivedAt?: number; organization: AffiliateAccountIdentity; member: AffiliateAccountIdentity; }; ``` ### account/profile_update Apply only fields present in `changes`; absence means unchanged. #### Profile update event ```json { "v": 1, "t": "account", "op": "profile_update", "id": "profile-1", "ts": 1772000001060, "d": { "actor": { "id": "10228272", "handle": "@TeamYouTube", "name": "TeamYouTube", "profileImage": "https://pbs.twimg.com/media/avatar.jpg", "websiteUrl": "https://youtube.com" }, "changes": { "handle": "@TeamYouTube", "name": "Team YouTube", "websiteUrl": "https://youtube.com/new" }, "eventId": "profile-1", "kind": "PROFILE", "observedAt": 1772000001050, "previous": { "handle": "@OldTeam" }, "receivedAt": 1772000001050 } } ``` ### account/follow Store the observed relationship using stable actor and target identifiers. #### Follow event ```json { "v": 1, "t": "account", "op": "follow", "id": "follow-1", "ts": 1772000001060, "d": { "actor": { "id": "10228272", "handle": "@TeamYouTube" }, "eventId": "follow-1", "kind": "FOLLOW", "observedAt": 1772000001050, "target": { "id": "4398626122", "handle": "@OpenAI" }, "receivedAt": 1772000001050 } } ``` ### account/unfollow Remove the observed relationship using the same identifiers. #### Unfollow event ```json { "v": 1, "t": "account", "op": "unfollow", "id": "unfollow-1", "ts": 1772000001060, "d": { "actor": { "id": "10228272", "handle": "@TeamYouTube" }, "eventId": "unfollow-1", "kind": "UNFOLLOW", "observedAt": 1772000001050, "target": { "id": "4398626122", "handle": "@OpenAI" }, "receivedAt": 1772000001050 } } ``` ### account/affiliate_update Apply the `added` or `removed` action idempotently to `(organization.id, member.id)`. Use `eventId` only to suppress an exact replay. Keyword filters do not apply. Replay stored changes with `GET /api/history?type=AFFILIATE`. History is not a current-list snapshot and does not backfill changes from before the feature was enabled. #### Affiliate update event ```json { "v": 1, "t": "account", "op": "affiliate_update", "id": "affiliate-update-1", "ts": 1772000001060, "d": { "action": "added", "organization": { "id": "10228272", "handle": "@TeamYouTube", "name": "TeamYouTube", "profileImage": "https://pbs.twimg.com/media/avatar.jpg", "websiteUrl": "https://youtube.com" }, "member": { "id": "4398626122", "handle": "@OpenAI", "name": "OpenAI", "profileImage": "https://pbs.twimg.com/media/member-avatar.jpg" }, "eventId": "affiliate-update-1", "observedAt": 1772000001050, "receivedAt": 1772000001050 } } ``` ## Callout events Follow pump.fun callouts, author updates, replies, and reposts on your WebSocket. Alert on the first event, then merge the full details that usually follow within a few seconds. Canonical URL: https://tweetstream.io/docs/callouts ### Select callout accounts In the Callouts tab, add a pump.fun username, Solana wallet, or profile URL. Labels are optional. - Use a Solana wallet for the account, regardless of the token's chain. - Minimum: 10 accounts. Pro, Scale, and Ultra Speed: 100. Pending additions count toward the limit. ### account/callout Alert on this event. `d.platform` is `pump_fun`; caller username and token address are always present. The first event may lack the token name, market cap, SOL and USD prices, the caller's position (holding, cost, value, and PnL), and attached media. In an author update, `d.text` may be a shortened preview. The complete callout follows as `account/callout_update`. Optional `d.token.chainId` uses CAIP-2: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` for Solana mainnet; `eip155:56`, `eip155:999`, `eip155:4663`, or `eip155:8453` for EVM chains. When absent, the chain is unspecified. Text, media, positions, and token/price details are optional. Optional images: `d.caller.image` (avatar), `d.token.image` (token artwork). - Optional `d.kind`: `callout`, `author_update`, `reply`, or `repost`. Author updates are new posts, not enrichment. - `d.caller` is the tracked actor. `d.reference` holds the original author, text, and media; `d.reference.reply` holds a reposted reply and its author, not the reposter. - `replyId` identifies a reply or author update. Optional `parentReplyId` and `rootReplyId` link the thread; `calloutId` identifies the original callout. - Exact decimal prices: `calloutPrice` / `maxPriceSol` (SOL), `calloutPriceUsd` / `maxPriceUsd` (USD). Keep strings or use a decimal library. USD prices do not imply SOL prices. - `marketCapUsd` and `multiple` are optional numbers. Position values are exact decimal strings: `amountHeld` is a token amount, `pnlPercentage` a percentage, and `*Usd` fields USD amounts. #### Callout event type ```typescript type CalloutCaller = { username: string; image?: string; }; type CalloutReply = { caller: CalloutCaller; replyId: string; parentReplyId?: string; rootReplyId?: string; text?: string; mediaUrl?: string; }; type CalloutEvent = { platform: 'pump_fun'; caller: CalloutCaller; kind?: 'callout' | 'author_update' | 'reply' | 'repost'; text?: string; mediaUrl?: string; // Required for replies and author updates. replyId?: string; parentReplyId?: string; rootReplyId?: string; reference?: { caller: CalloutCaller; text?: string; mediaUrl?: string; reply?: CalloutReply; }; position?: { amountHeld?: string; valueUsd?: string; costBasisUsd?: string; pnlUsd?: string; pnlPercentage?: string; realizedPnlUsd?: string; }; token: { address: string; chainId?: string; symbol?: string; name?: string; image?: string; }; url?: string; marketCapUsd?: number; // SOL, exact decimal. calloutPrice?: string; // USD, exact decimal. calloutPriceUsd?: string; multiple?: number; // SOL peak, exact decimal. maxPriceSol?: string; // USD peak, exact decimal. maxPriceUsd?: string; calloutId: string; createdAt: number; receivedAt?: number; }; type CalloutUpdateEvent = CalloutEvent & { // Original envelope id, not calloutId. updateOf: string; }; type PerpCalloutEvent = { platform: 'pump_fun'; caller: CalloutCaller; // The perpetual market and the original callout's stance. market: { // For example 'hyperliquid'. venue: string; // The venue's market symbol, case kept: 'BTC', 'xyz:CL'. symbol: string; name?: string; image?: string; side: 'long' | 'short'; // Exact decimal multiplier, for example '10' or '2.5'. leverage: string; // USD, exact decimals. entryPriceUsd?: string; closePriceUsd?: string; closedAt?: number; }; kind?: 'callout' | 'author_update' | 'reply' | 'repost'; text?: string; mediaUrl?: string; // Required for replies and author updates. replyId?: string; parentReplyId?: string; rootReplyId?: string; reference?: CalloutEvent['reference']; // The acting account's position snapshot, exact decimals. // market.side is the original callout's stance, not this position's direction. position?: { // Coin units. size?: string; notionalUsd?: string; marginUsd?: string; pnlUsd?: string; // Of margin. pnlPercentage?: string; realizedPnlUsd?: string; }; // USD, exact decimal. calloutPriceUsd?: string; // Return multiple, leverage included. multiple?: number; calloutId: string; createdAt: number; receivedAt?: number; }; ``` #### First callout event ```json { "v": 1, "t": "account", "op": "callout", "id": "callout.0123456789abcdef0123", "ts": 1772000001060, "d": { "platform": "pump_fun", "caller": { "username": "CryptoCalls", "image": "https://cdn.example/avatar.png" }, "kind": "callout", "text": "Watching this token.", "token": { "address": "So11111111111111111111111111111111111111112", "chainId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "symbol": "ABC" }, "url": "https://pump.fun/callouts/So11111111111111111111111111111111111111112/9ab3177c-7b35-4d99-9cca-8b426f74a270", "calloutId": "9ab3177c-7b35-4d99-9cca-8b426f74a270", "createdAt": 1772000001000, "receivedAt": 1772000001050 } } ``` #### Repost of another author's reply ```json { "v": 1, "t": "account", "op": "callout", "id": "callout.repost-example", "ts": 1772000003060, "d": { "platform": "pump_fun", "kind": "repost", "caller": { "username": "MarketReader" }, "token": { "address": "So11111111111111111111111111111111111111112" }, "calloutId": "9ab3177c-7b35-4d99-9cca-8b426f74a270", "createdAt": 1772000003000, "reference": { "caller": { "username": "CryptoCalls" }, "text": "Watching this token.", "reply": { "caller": { "username": "ReplyAuthor" }, "replyId": "reply-example", "text": "Watching the volume too." } } } } ``` ### account/callout_update Usually within a few seconds, this event carries the complete callout, including any details the first event lacked. Merge it into the original row without another alert. - Deduplicate by this envelope's `id`. `d.updateOf` points to the original envelope `id`, not `calloutId`. - Merge supplied fields, including nested `caller`, `token`, `position`, and `reference` fields. Omitted fields do not erase earlier values. - If the original is missing, store or ignore the update; do not treat it as a new callout. - Updates are optional. Show initial content even if no update arrives. #### Follow-up with full details ```json { "v": 1, "t": "account", "op": "callout_update", "id": "callout_update.556abf0021a7ff937a1a804ec0a0c245d497bcc6090af66179e74ce03c0970e0", "ts": 1772000001840, "d": { "platform": "pump_fun", "updateOf": "callout.0123456789abcdef0123", "caller": { "username": "CryptoCalls" }, "kind": "callout", "mediaUrl": "https://cdn.example/chart.png", "token": { "address": "So11111111111111111111111111111111111111112", "symbol": "ABC", "name": "Alpha Beta", "image": "https://cdn.example/token.png" }, "marketCapUsd": 156230.75, "calloutPrice": "0.00000125", "calloutPriceUsd": "0.00018750", "position": { "amountHeld": "2500000", "costBasisUsd": "312.50", "valueUsd": "468.75", "pnlUsd": "156.25", "pnlPercentage": "50" }, "calloutId": "9ab3177c-7b35-4d99-9cca-8b426f74a270", "createdAt": 1772000001000 } } ``` #### Alert once, then merge ```typescript type Json = Record; type CalloutMessage = | { op: 'callout'; id: string; d: CalloutEvent } | { op: 'callout_update'; id: string; d: CalloutUpdateEvent }; declare function sendAlert(callout: CalloutEvent): void; const isObject = (value: unknown): value is Json => typeof value === 'object' && value !== null && !Array.isArray(value); // Supplied fields win, nested objects merge, omitted fields keep their value. function merge(row: Json, details: Json): Json { const merged: Json = { ...row }; for (const [key, value] of Object.entries(details)) { const current = merged[key]; merged[key] = isObject(current) && isObject(value) ? merge(current, value) : value; } return merged; } // One row per callout, keyed by the first event's envelope id. const rows = new Map(); function handleCallout(message: CalloutMessage) { if (message.op === 'callout') { if (rows.has(message.id)) return; rows.set(message.id, message.d); sendAlert(message.d); return; } // Fill in the row from the first event. Never alert here. const { updateOf, ...details } = message.d; const row = rows.get(updateOf); if (row) rows.set(updateOf, merge(row, details)); } ``` ### account/perp_callout Callouts on perpetual markets arrive as this operation, never as `account/callout`. `d.market` takes the place of `d.token`, so a spot token handler never receives a perpetual. - `d.market` is the original callout's stance: `venue` (such as `hyperliquid`), the market `symbol` with its case kept (`BTC`, `xyz:CL`), `side` (`long` or `short`), and `leverage`, an exact decimal multiplier. Optional `entryPriceUsd`, `closePriceUsd`, and `closedAt` complete it. - `d.kind`, `replyId`, and `reference` work as on `account/callout`. A reply or repost carries the original callout's `market`, not the replier's. - Optional `d.position` is the acting account's position snapshot, in exact decimal strings: `size` in coin units, `notionalUsd`, `marginUsd`, `pnlUsd`, `pnlPercentage` of margin, and `realizedPnlUsd`. `market.side` is the original callout's stance, not this position's direction. - `calloutPriceUsd` is the market price at the callout. `multiple` is the return multiple, leverage included. - No `account/callout_update` follows a perpetual callout. Deduplicate by envelope `id`. #### Perpetual callout ```json { "v": 1, "t": "account", "op": "perp_callout", "id": "callout.0123456789abcdef0123", "ts": 1772000001060, "d": { "platform": "pump_fun", "caller": { "username": "CryptoCaller" }, "market": { "venue": "hyperliquid", "symbol": "ZEC", "name": "Zcash", "side": "long", "leverage": "10", "entryPriceUsd": "1155.0967741935483" }, "calloutPriceUsd": "1138.8", "multiple": 0.8056, "text": "Thesis text", "kind": "callout", "position": { "size": "0.31", "notionalUsd": "351.85", "marginUsd": "32.053309", "pnlUsd": "-6.229999999999973", "pnlPercentage": "-19.436370828359635", "realizedPnlUsd": "0" }, "calloutId": "b7cccaa0-6ca2-46b8-bad4-79688a083be6", "createdAt": 1772000001000, "receivedAt": 1772000001050 } } ``` ### Use identifiers and timestamps Deduplicate by envelope `id`. Replies and reposts share the original `calloutId`, not the envelope ID. - `d.createdAt`: occurrence creation time. - `d.receivedAt`: optional TweetStream receipt time. - Envelope `ts`: preparation time. ## FOMO theses and token verification Track FOMO users and coins in the FOMO tab. Receive theses and observed token verification on your existing WebSocket. Canonical URL: https://tweetstream.io/docs/fomo ### Choose users and coins - Minimum includes 10 FOMO users and 10 FOMO coins. Pro, Scale, and Ultra Speed include 100 users and 100 coins. These limits are independent of each other and your X watchlist. - Track a user to receive theses they author. Track a coin to receive theses from any author and its first observed verification. - Manage both lists in the dashboard's FOMO tab. FOMO events are live-only; History does not replay them. ### Manage lists through REST Use Bearer API-key authentication with `/api/callouts`. Set `platform` to `fomo_user` or `fomo_coin` for management; both emit events with `d.platform: fomo`. - [`GET /api/callouts`](https://tweetstream.io/docs/api/list-fomo-and-callout-subscriptions.md) - [`PUT /api/callouts`](https://tweetstream.io/docs/api/add-fomo-or-callout-subscription.md) - [`DELETE /api/callouts`](https://tweetstream.io/docs/api/remove-fomo-or-callout-subscription.md) - `GET` returns `callers`, `pending`, and per-platform `limits`. Read `limits` for current capacity; all values are `0` without an active eligible plan. The legacy top-level `limit` stays `10`. - `PUT` accepts `{ platform, input, label? }`. Use a FOMO username or profile URL for users. For coins, use a FOMO coin URL or `network:address`; a plain contract address must resolve to one network. The response contains `caller`; fetch the list again after a change. - `DELETE` accepts `{ platform, callerId }` to remove a tracked item, or `{ platform, intentId }` to cancel a pending item. Use identifiers from `GET`; success returns `removed: true`. ### account/thesis Read `d.author`, `d.thesis`, and `d.coin`. `d.platform` is `fomo`. Position data and coin metadata appear when available. Use `thesis.id` for the thesis and `(coin.networkId, coin.address)` for the coin. #### FOMO event types ```typescript type FomoCoin = { address: string; networkId: number; name?: string; symbol?: string; image?: string; metadataObservedAt?: number; priceUsd?: string; marketCapUsd?: string; liquidityUsd?: string; volume24hUsd?: string; change24hPercent?: string; }; type FomoThesisEvent = { platform: 'fomo'; coin: FomoCoin; author: { id: string; username: string; verified: boolean; displayName?: string; avatar?: string; twitter?: string; }; thesis: { id: string; text: string; createdAt: number; likes: number; replies: number; tradeId?: string; parentId?: string; segments?: Array<{ text: string; link?: string }>; }; position?: { tokenAmount?: string; usdValue?: string; unrealizedPnlUsd?: string; realizedPnlUsd?: string; unrealizedPnlPercent?: string; realizedPnlPercent?: string; closedAt?: number; }; observedAt?: number; receivedAt?: number; }; type FomoTokenVerifiedEvent = { platform: 'fomo'; coin: FomoCoin; observedAt: number; receivedAt?: number; }; ``` #### Thesis event ```json { "v": 1, "t": "account", "op": "thesis", "id": "fomo:thesis:thesis-1", "ts": 1772000001060, "d": { "platform": "fomo", "coin": { "address": "So11111111111111111111111111111111111111112", "networkId": 1399811149, "name": "Example Token", "symbol": "EXM", "image": "https://cdn.example/token.png", "metadataObservedAt": 1772000000900, "priceUsd": "0.00000123456789012345", "marketCapUsd": "123456.7890123456789" }, "author": { "id": "user-1", "username": "SignalDesk", "displayName": "Signal Desk", "avatar": "https://cdn.example/avatar.png", "twitter": "signaldesk", "verified": true }, "thesis": { "id": "thesis-1", "text": "Watching liquidity", "createdAt": 1772000001000, "likes": 2, "replies": 1, "tradeId": "trade-1", "segments": [ { "text": "Watching liquidity", "link": "https://example.com/thesis" } ] }, "position": { "tokenAmount": "549351.552212985712345", "usdValue": "12.34567890123456789", "realizedPnlUsd": "0" }, "receivedAt": 1772000001050 } } ``` ### account/token_verified A coin-only event reports the first time TweetStream observes verification for a tracked coin. It contains no author, thesis, or position. `observedAt` is an observation time, not the time verification happened. Verification is not a safety or investment recommendation. #### Token verification observed ```json { "v": 1, "t": "account", "op": "token_verified", "id": "fomo:verified:1399811149:coin:1772000001000", "ts": 1772000001060, "d": { "platform": "fomo", "coin": { "address": "So11111111111111111111111111111111111111112", "networkId": 1399811149, "symbol": "EXM" }, "observedAt": 1772000001000, "receivedAt": 1772000001050 } } ``` ### Read timestamps and market values - Timestamps are Unix milliseconds. `thesis.createdAt` is the thesis creation time; optional `receivedAt` is TweetStream's receipt time; envelope `ts` is the delivery preparation time. - Coin market values and position amounts are decimal strings. Coin market values include `metadataObservedAt`; they describe that observation, not a guaranteed current quote. - Make exact envelope `id` replays idempotent. Missing optional fields mean unavailable, not zero. Published X latency figures do not apply to FOMO. ## Charity events Enable charity alerts in settings and consume live `charity/added` events. Canonical URL: https://tweetstream.io/docs/charity ### charity/added Charity events are live-only. Use the envelope `id` to ignore an exact replay. #### Charity added type ```typescript type CharityAddedEvent = { id: string; name: string; slug: string; enabled: boolean; taxId?: string; location?: { city?: string; state?: string; country?: string; }; observedAt: number; }; ``` #### Charity added event ```json { "v": 1, "t": "charity", "op": "added", "id": "4ffccf6e-66d4-555a-af5d-ceb36c10e3f0", "ts": 1772000001060, "d": { "id": "4ffccf6e-66d4-555a-af5d-ceb36c10e3f0", "name": "Council on Foreign Relations", "slug": "council-on-foreign-relations", "enabled": true, "taxId": "13-1628168", "location": { "city": "New York City", "state": "NY", "country": "US" }, "observedAt": 1772000001060 } } ``` ## News events and history Select publications, consume `news/article` live, and use the separate cursor-based News History API for stored articles. Canonical URL: https://tweetstream.io/docs/news ### Select publications Use the dashboard or `GET` and `PATCH /api/news/sources` to read and change your enabled publications. - [`GET /api/news/sources`](https://tweetstream.io/docs/api/list-news-sources.md) - [`PATCH /api/news/sources`](https://tweetstream.io/docs/api/set-news-source-enabled.md) #### News sources response [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-news-sources#responses) ### news/article Enabled publications send articles on the same WebSocket as other TweetStream events. #### News article type ```typescript type NewsSource = { id: string; name: string; }; type NewsMedia = { url: string; type?: 'image' | 'video'; caption?: string; }; type NewsArticle = { source: NewsSource; url: string; title: string; publishedAt: string; receivedAt: number; modifiedAt?: string; primaryCategory?: string; categories: string[]; author?: string; keywords: string[]; description?: string; summary?: string; media: NewsMedia[]; content?: string; language?: string; copyright?: string; }; ``` #### News article event ```json { "v": 1, "t": "news", "op": "article", "id": "news_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "ts": 1787786858123, "d": { "source": { "id": "bbc-news", "name": "BBC News" }, "url": "https://www.bbc.com/news/articles/example", "title": "Markets open after the holiday", "publishedAt": "2026-08-26T23:27:38.000Z", "receivedAt": 1787786858123, "primaryCategory": "Business", "categories": ["Business"], "author": "BBC News", "keywords": ["markets"], "description": "A brief description supplied by the publication.", "summary": "Markets reopened after the holiday.", "media": [ { "url": "https://ichef.bbci.co.uk/news/example.jpg", "type": "image", "caption": "A market floor" } ], "content": "The stored article text, when available.", "language": "en", "copyright": "BBC" } } ``` ### News History API `GET /api/news/history` returns stored articles from enabled publications in `(receivedAt DESC, id DESC)` order. `limit` defaults to 50 and accepts 1 through 100. Continue with `nextCursor`. A page can contain fewer results when it reaches the response-size limit; this does not promise a retention duration or historical completeness. - [`GET /api/news/history`](https://tweetstream.io/docs/api/get-news-history.md) #### News history type ```typescript type NewsSource = { id: string; name: string; }; type NewsMedia = { url: string; type?: 'image' | 'video'; caption?: string; }; type NewsArticle = { source: NewsSource; url: string; title: string; publishedAt: string; receivedAt: number; modifiedAt?: string; primaryCategory?: string; categories: string[]; author?: string; keywords: string[]; description?: string; summary?: string; media: NewsMedia[]; content?: string; language?: string; copyright?: string; }; type HistoricalNewsArticle = { id: string; source: NewsSource; url: string; title: string; publishedAt: string; receivedAt: string; modifiedAt: string | null; primaryCategory: string | null; categories: string[]; author: string | null; keywords: string[]; description: string | null; summary: string | null; media: NewsMedia[]; content: string | null; language: string | null; copyright: string | null; }; type NewsHistoryResult = { data: HistoricalNewsArticle[]; metadata: { count: number; nextCursor: string | null; sourceId?: string; }; }; ``` #### Fetch news history ```typescript const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY"); const url = new URL( "https://api.tweetstream.io/api/news/history", ); url.searchParams.set("sourceId", "bbc-news"); url.searchParams.set("limit", "1"); const response = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}`, }, }); if (!response.ok) { const detail = await response.text(); throw new Error(`News history failed (${response.status}): ${detail}`); } const page = await response.json(); console.log(page.data); if (page.metadata.nextCursor) { url.searchParams.set("before", page.metadata.nextCursor); } ``` #### News history response ```json { "data": [ { "id": "news_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "source": { "id": "bbc-news", "name": "BBC News" }, "url": "https://www.bbc.com/news/articles/example", "title": "Markets open after the holiday", "publishedAt": "2026-08-26T23:27:38.000Z", "receivedAt": "2026-08-26T23:27:38.123Z", "modifiedAt": null, "primaryCategory": "Business", "categories": ["Business"], "author": "BBC News", "keywords": ["markets"], "description": "A brief description supplied by the publication.", "summary": "Markets reopened after the holiday.", "media": [ { "url": "https://ichef.bbci.co.uk/news/example.jpg", "type": "image", "caption": "A market floor" } ], "content": "The stored article text, when available.", "language": "en", "copyright": "BBC" } ], "metadata": { "count": 1, "nextCursor": "v1.MTc4Nzc4Njg1ODEyMwpuZXdzXzAxMjM0NTY3ODlhYmNkZWYwMTIzNDU2Nzg5YWJjZGVmMDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY", "sourceId": "bbc-news" } } ``` ## Control messages Control messages keep a connection authenticated and report handle-management command results. Canonical URL: https://tweetstream.io/docs/control ### Send auth_ping Send `{ "op": "auth_ping" }` when your application needs an authentication check. This is a client message, not a server event. #### Authentication ping ```json { "op": "auth_ping" } ``` ### control/auth_pong A successful authentication check returns an empty data object. #### Authentication pong ```json { "v": 1, "t": "control", "op": "auth_pong", "ts": 1772000001060, "d": {} } ``` ### control/twitter_handles_result Read every result row. Idempotent success and row failures can appear in one response. #### Handle result type ```typescript type TwitterHandlesResult = { action: 'follow' | 'unfollow'; requestId: string | null; results: Array<{ input: string; state: | 'added' | 'already_following' | 'invalid_input' | 'duplicate' | 'not_found' | 'failed' | 'removed' | 'not_following'; message?: string; }>; error: string | null; }; ``` #### Handle result event ```json { "v": 1, "t": "control", "op": "twitter_handles_result", "ts": 1772000001060, "d": { "action": "follow", "error": null, "requestId": "req-1", "results": [ { "input": "@one", "state": "added" } ] } } ``` ### Manage handles over WebSocket Use the handle-management subprotocol to add or remove monitored accounts through a long-running backend socket, without a separate REST request. #### Follow handles over WebSocket ```typescript import WebSocket from "ws"; type HandleManagementEvent = { t?: string; op?: string; d?: { error?: string | null; results?: Array<{ input: string; state: string }>; }; }; const ws = new WebSocket("wss://ws-global.tweetstream.io/ws", [ "tweetstream.handle-management", `tweetstream.auth.token.${process.env.TWEETSTREAM_API_KEY}`, ]); ws.on("open", () => { ws.send(JSON.stringify({ type: "twitter_handles", action: "follow", handles: ["marketdesk", "realDonaldTrump"], requestId: crypto.randomUUID(), })); }); ws.on("message", (raw) => { const event = JSON.parse(raw.toString()) as HandleManagementEvent; if (event.t === "control" && event.op === "twitter_handles_result") { console.log(event.d?.results, event.d?.error); } }); ``` ## History API Replay stored content, profile, follow, and affiliate events through the History API, or look up one post or account. Canonical URL: https://tweetstream.io/docs/history-api ### Request history Use `GET /api/history` to replay stored events after reconnecting or inspect a specific time window. - [`GET /api/history`](https://tweetstream.io/docs/api/get-history.md) #### Check access Pro, Scale, and Ultra Speed can request every History event type. Standard keys query base-plan tracked accounts; Ultra keys query selected Ultra accounts. Supported types are `TWEET`, `PROFILE`, `FOLLOW`, and `AFFILIATE`. Delete, pin, and unpin remain live-only events. #### Set filters Without a handle filter, History searches all active accounts tracked by the key. A filter can include only handles that key currently tracks. | Parameter | Required | Notes | | --- | --- | --- | | `handle`, `handles`, `handle[]`, `handles[]` | No | One handle, repeated handles, or comma-separated handles | | `startDate` | No | ISO datetime lower bound | | `endDate` | No | ISO datetime upper bound | | `limit` | No | Defaults to 100; maximum 1000 | | `type` | No | `TWEET`, `PROFILE`, `FOLLOW`, or `AFFILIATE`; case-insensitive. Defaults to `TWEET` | | `cursor` | No | Opaque `nextCursor` from the previous page; keep every other filter unchanged | ##### History request ```typescript const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY"); const response = await fetch( "https://api.tweetstream.io/api/history?limit=25&type=TWEET", { headers: { Authorization: `Bearer ${apiKey}`, }, }, ); if (!response.ok) { const detail = await response.text(); throw new Error(`History failed (${response.status}): ${detail}`); } const page = await response.json(); console.log(page.data); ``` ### Page through a bounded window History returns up to 1000 rows per request in stable newest-first order. #### Set both bounds Capture one `endDate`, choose a `startDate`, and keep both values unchanged for every page in the replay. #### Continue with nextCursor Send each returned `nextCursor` with the same type, handles, and date bounds. A null cursor ends the window. Process rows idempotently and keep live lifecycle handlers active because History replays stored event families separately from live-only state changes. ### Read the response Read the rows and request metadata before advancing the replay window. #### Read rows and metadata Results use stable newest-first traversal. `metadata.count` reports the returned rows, `metadata.nextCursor` continues the same filtered query, and a null cursor ends the result set. Older stored `FOLLOW` rows can have an empty `target`; treat the target identity as unavailable and continue processing the event. ##### History response types ```typescript type VerifiedType = 'blue' | 'business' | 'government' | 'verified' | 'none'; type TweetVerifiedLabel = { badge: string | null; description: string; url: string | null; }; type TweetAuthor = { banner?: string; bio?: string; followersCount?: number; followingCount?: number; id?: string; joinedAt?: number; location?: string; metrics?: { likes?: number; tweets?: number; }; // Includes a leading @ when present, for example "@elonmusk". handle?: string; name?: string; // History stores X and Truth Social posts; Binance Square content is live-only. platform?: 'twitter' | 'truth_social'; profileImage?: string; // The account's own website, when it has one. url?: string; verifiedLabel?: TweetVerifiedLabel; verifiedType?: VerifiedType; }; type AccountEventActor = TweetAuthor & { websiteUrl?: string; }; type ProfileUpdateEvent = { kind: 'PROFILE'; eventId: string; observedAt: number; receivedAt?: number; actor: AccountEventActor; changes: { avatar?: string; banner?: string; bio?: string; handle?: string; location?: string; name?: string; verifiedLabel?: TweetVerifiedLabel | null; websiteUrl?: string | null; }; previous?: { avatar?: string; banner?: string; bio?: string; handle?: string; location?: string; name?: string; verifiedLabel?: TweetVerifiedLabel | null; websiteUrl?: string | null; }; }; type FollowEvent = { kind: 'FOLLOW'; eventId: string; observedAt: number; receivedAt?: number; actor: AccountEventActor; target: AccountEventActor; }; type UnfollowEvent = { kind: 'UNFOLLOW'; eventId: string; observedAt: number; receivedAt?: number; actor: AccountEventActor; target: AccountEventActor; }; type AffiliateAccountIdentity = AccountEventActor & { id: string; }; type AffiliateUpdateEvent = { action: 'added' | 'removed'; eventId: string; observedAt: number; receivedAt?: number; organization: AffiliateAccountIdentity; member: AffiliateAccountIdentity; }; type TweetMeta = { tweetId: string; // Pair with tweetId when merging enrichment. When omitted, use twitter. platform?: 'twitter' | 'truth_social'; ocr?: { text: string; }; detected?: { tokens?: Array<{ symbol?: string; name?: string; contract?: string; chain?: string; networkId?: number; priceUsd?: number; sources: Array<'text' | 'ocr'>; }>; cex?: Array<{ exchange: 'bybit' | 'binance' | 'hyperliquid'; symbol?: string; priceUsd?: number; url?: string; baseAsset?: string; quoteAsset?: string; sources: Array<'text' | 'ocr'>; }>; prediction?: Array<{ exchange: 'polymarket' | 'kalshi'; marketId?: string; title?: string; priceUsd?: number; url?: string; sources: Array<'text' | 'ocr'>; }>; }; }; type HistoryMedia = { url: string; type?: 'image' | 'video' | 'gif'; thumbnail?: string; }; type TweetUrl = { url: string; name?: string; tco?: string; }; type TweetMention = { handle?: string; id?: string; name?: string; }; type HistoryTweetArticle = { description?: string; id?: string; publishedAt?: number; text?: string; thumbnail?: string; title?: string; updatedAt?: number; url?: string; }; type HistoryTweetPollChoice = { id?: string; image?: string; label?: string; votes?: number; }; type HistoryTweetPoll = { choices: HistoryTweetPollChoice[]; endsAt?: number; totalVotes?: number; updatedAt?: number; }; type TweetContentKind = 'post' | 'reply' | 'quote' | 'retweet'; type HistoryTweetReference = { article?: HistoryTweetArticle; type: 'reply' | 'quote' | 'retweet'; tweetId?: string; text?: string; translatedText?: string; author?: TweetAuthor; media?: HistoryMedia[]; poll?: HistoryTweetPoll; quoted?: HistoryTweetReference; subtweet?: HistoryTweetReference; }; type TweetContent = { tweetId: string; kind: TweetContentKind; // Original tweet text when the stored content includes both original and // translated text. text: string; translatedText?: string; createdAt: number; author: TweetAuthor; article?: HistoryTweetArticle; link?: string; media?: HistoryMedia[]; mentions?: TweetMention[]; poll?: HistoryTweetPoll; // Epoch ms from the realtime payload when the stored content includes it. receivedAt?: number; urls?: TweetUrl[]; ref?: HistoryTweetReference; quoted?: HistoryTweetReference; }; type HistoricalContent = | TweetContent | ProfileUpdateEvent | FollowEvent | UnfollowEvent | AffiliateUpdateEvent; type HistoricalTweetResponse = { tweetId: string; twitterId: string; twitterHandle: string | null; body: string; time: string; // ISO TweetStream receipt time for the historical event. receivedTime: string; link: string; messageType: 'TWEET' | 'PROFILE' | 'FOLLOW' | 'AFFILIATE'; content: HistoricalContent; meta?: TweetMeta; }; type HistoryResult = { data: HistoricalTweetResponse[]; metadata: { count: number; nextCursor: string | null; handle?: string; handles?: string[]; startDate?: string; endDate?: string; type?: 'TWEET' | 'PROFILE' | 'FOLLOW' | 'AFFILIATE'; }; }; ``` ##### History response [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### Map affiliate rows For `AFFILIATE`, the top-level account is the organization and `content` matches the live `affiliate_update` payload. ### Handle errors | Status | Body | Meaning | | --- | --- | --- | | `400` | `{ "error": "Invalid query parameters" }` | Malformed dates, limit, type, or handle | | `400` | `{ "error": "Invalid handle provided", "handle": "..." }` | Handle validation failed | | `400` | `{ "error": "startDate must be before endDate" }` | Date range is reversed | | `400` | `{ "error": "Invalid cursor" }` | Cursor is malformed or does not match the other filters | | `401` | `{ "error": "Missing or invalid API key" }` | Missing or malformed bearer token | | `401` | `{ "error": "Invalid API key" }` | Bearer token was well-formed but does not match an active API key | | `403` | `{ "error": "History is available on Pro, Scale, and Ultra Speed" }` | Plan does not include the requested History type | | `403` | `{ "error": "Your subscription is not active", "message": "Please ensure your subscription is active", "status": "PAST_DUE" }` | Subscription state does not allow history | | `403` | `{ "error": "Handle ... is not among your tracked accounts" }` | Requested replay handle is outside your watchlist | | `429` | `{ "error": "Too many history requests", "retryAfterSeconds": 60 }` | Rate limit exceeded | ### Look up a post `GET /api/tweet/{id}` returns one post and its engagement counts. `{id}` is the post ID, 1 to 20 digits. - [`GET /api/tweet/{id}`](https://tweetstream.io/docs/api/lookup-tweet.md) - `tweet` has the same fields as `content` in a `TWEET` History row. - A reply that also quotes a post has `kind` `reply`, its parent in `ref`, and the post it quotes in `quoted`. - `metrics` holds `likes`, `replies`, `reposts`, `quotes`, `bookmarks`, and `views`. `views` can be null. #### Post lookup request ```typescript const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY"); const response = await fetch( "https://api.tweetstream.io/api/tweet/1234567890", { headers: { Authorization: `Bearer ${apiKey}`, }, }, ); if (!response.ok) { const detail = await response.text(); throw new Error(`Lookup failed (${response.status}): ${detail}`); } const { tweet, metrics } = await response.json(); console.log(tweet.text, metrics.likes); ``` #### Post lookup response [Use the first complete copy of this example.](https://tweetstream.io/docs/api/lookup-tweet#responses) ### Look up an account `GET /api/user/{id}` returns one account's profile. `{id}` is a numeric account ID or a handle, with or without `@`. Digits alone are read as an account ID, so a handle made only of digits needs the `@`. - [`GET /api/user/{id}`](https://tweetstream.io/docs/api/lookup-user.md) - `user` has the same fields as `author` in WebSocket post events. - `pinnedTweet` is the account's pinned post, with the same fields as `tweet` in a post lookup. TweetStream fills it in only for accounts it has seen pin a post. It is null otherwise, after the account unpins, or when the post can't be shown right now. #### Account lookup response [Use the first complete copy of this example.](https://tweetstream.io/docs/api/lookup-user#responses) ### Lookup access and errors Any paid or trialing plan can use lookups. Each account can make 60 lookups per minute across both endpoints, in bursts of up to 10. Up to 4 can be in progress at once. On `429`, wait the number of seconds in `retryAfterSeconds` (also sent as `Retry-After`) before retrying. | Status | Body | Meaning | | --- | --- | --- | | `400` | `{ "error": "Invalid post ID" }` | The post ID is not 1 to 20 digits | | `400` | `{ "error": "Invalid account ID or handle" }` | The account ID or handle is malformed | | `401` | `{ "error": "Missing or invalid Authorization header" }` | No bearer token was sent | | `401` | `{ "error": "Invalid API key" }` | The token does not match an API key | | `403` | `{ "error": "An active subscription is required" }` | The account has no paid or trialing subscription | | `404` | `{ "error": "Post not found" }` | The post was not found or is not public | | `404` | `{ "error": "Account not found" }` | No account has this ID or handle | | `429` | `{ "error": "Rate limit exceeded", "retryAfterSeconds": 1 }` | The account reached its lookup limit | | `429` | `{ "error": "Too many lookups in progress", "retryAfterSeconds": 1 }` | The account already has 4 lookups in progress | | `503` | `{ "error": "Lookup is temporarily unavailable" }` | Retry later, after `Retry-After` when it is sent | | `503` | `{ "error": "Authentication service unavailable" }` | The API key could not be checked. Retry later | ### Search posts `GET /api/search/posts` returns recent X posts that match an X search query, in X's Latest order (not strictly by ID). - [`GET /api/search/posts`](https://tweetstream.io/docs/api/search-posts.md) - `query` is required: an X search query, operators included, up to 512 characters. - `limit` is optional: 1 to 40 posts, 20 by default. - Each item in `posts` is the post lookup's `tweet` object with its `metrics` inside. `views` is null in search. - Results can be up to 30 seconds old. - No match is a `200` with `"posts": []` and `"next": null`. #### Post search request ```typescript const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY"); const url = new URL("https://api.tweetstream.io/api/search/posts"); url.searchParams.set("query", "solana lang:en -is:retweet"); url.searchParams.set("limit", "20"); const response = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}`, }, }); if (!response.ok) { const detail = await response.text(); throw new Error(`Search failed (${response.status}): ${detail}`); } const { posts, next } = await response.json(); console.log(posts.length, next); ``` #### Post search response [Use the first complete copy of this example.](https://tweetstream.io/docs/api/search-posts#responses) ### Get the next page `next` is the URL of the next page. Request it as it is, with the same API key, until it is `null`. - A `next` link works for 30 minutes. - A page can have fewer than `limit` posts before the end. Keep following `next`. - One search returns at most 100 posts; after that `next` is `null`. Pages can repeat a post, so deduplicate by `tweetId`. #### Read every page ```typescript const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY"); const query = "solana lang:en -is:retweet"; let url: string | null = `https://api.tweetstream.io/api/search/posts?query=${encodeURIComponent(query)}&limit=40`; while (url) { const response = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` }, }); if (!response.ok) { throw new Error(`Search failed (${response.status}): ${await response.text()}`); } const { posts, next } = await response.json(); for (const post of posts) console.log(post.tweetId, post.text); url = next; } ``` ### Search access and errors Pro, Scale, and Ultra Speed include post search, with either of the account's API keys. Each request costs one from the account's search allowance, `next` links included. The allowance is separate from lookups. On `429`, wait the number of seconds in `retryAfterSeconds` (also sent as `Retry-After`) before retrying. | Status | Body | Meaning | | --- | --- | --- | | `400` | `{ "error": "Search query is required" }` | `query` is missing or empty | | `400` | `{ "error": "Search query is too long" }` | `query` is over 512 characters | | `400` | `{ "error": "Invalid search query" }` | `query` has control characters or is sent twice | | `400` | `{ "error": "Invalid limit" }` | `limit` is not a whole number from 1 to 40, or is sent twice | | `400` | `{ "error": "This page link is invalid or has expired; start the search again" }` | The `next` link was changed or expired. Search again without `page` | | `401` | `{ "error": "Missing or invalid Authorization header" }` | No bearer token was sent | | `401` | `{ "error": "Invalid API key" }` | The token does not match an API key | | `403` | `{ "error": "Post search requires Pro, Scale, or Ultra Speed" }` | The account's plans don't include post search | | `405` | `—` | Only `GET` is supported | | `429` | `{ "error": "Rate limit exceeded", "retryAfterSeconds": 1 }` | Over the plan's searches per minute | | `429` | `{ "error": "Too many searches in progress", "retryAfterSeconds": 1 }` | Too many searches running at once | | `503` | `{ "error": "Post search is temporarily unavailable" }` | Try again shortly (after `Retry-After` if sent) | | `503` | `{ "error": "Authentication service unavailable" }` | The API key could not be checked. Try again shortly | #### Search allowance by plan When the account has more than one of these plans, the largest allowance applies. REST and MCP share it. | Plan | Requests per minute | In progress at once | | --- | --- | --- | | Pro | 60, in bursts of up to 10 | 4 | | Ultra Speed | 120, in bursts of up to 10 | 6 | | Scale | 300, in bursts of up to 10 | 10 | ## Accounts and settings Manage monitored accounts and optional event sources through authenticated REST endpoints and account settings. Canonical URL: https://tweetstream.io/docs/account-management ### Endpoints Send each request to `https://api.tweetstream.io` with `Authorization: Bearer `. | Method | Path | Use | | --- | --- | --- | | `POST` | `/api/add-account` | Add monitored accounts | | `DELETE` | `/api/remove-account` | Remove monitored accounts | | `GET` | `/api/me` | Read plan limits and usage | | `PATCH` | `/api/account-settings` | Change an account's Discord webhook and keywords | | `POST`, `DELETE` | `/api/affiliate-alerts` | Turn affiliate list alerts on or off | | `GET`, `POST`, `DELETE` | `/api/binance-square` | List Binance Square accounts or turn one on or off | ### Add and remove accounts Use the REST endpoints from your backend to change the watchlist. #### Send handles Send one handle or an array in `accounts`. A leading @ is optional, and matching is case-insensitive. - [`POST /api/add-account`](https://tweetstream.io/docs/api/add-accounts.md) - [`DELETE /api/remove-account`](https://tweetstream.io/docs/api/remove-accounts.md) ##### Add accounts ```typescript const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY"); const response = await fetch("https://api.tweetstream.io/api/add-account", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ accounts: ["marketdesk", "realDonaldTrump"], }), }); if (!response.ok && response.status !== 207) { const detail = await response.text(); throw new Error(`Add failed (${response.status}): ${detail}`); } console.log(await response.json()); ``` ##### Remove an account ```typescript const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY"); const response = await fetch("https://api.tweetstream.io/api/remove-account", { method: "DELETE", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ accounts: "marketdesk", }), }); if (!response.ok && response.status !== 207) { const detail = await response.text(); throw new Error(`Remove failed (${response.status}): ${detail}`); } console.log(await response.json()); ``` #### Choose the credential scope A standard API key updates the standard tracked-account list. An active Ultra key updates the Ultra selection and enforces its paid account limit. #### Read every result The response contains one result per handle plus a `summary` with `total`, `succeeded`, and `failed` counts. Use the row state, not only the HTTP status, before retrying. ##### Add result ```json { "action": "follow", "requestId": "8b4f9c9c-9e7b-4a0c-9c7d-2d4d6f0a9a25", "error": null, "results": [ { "input": "marketdesk", "state": "added" }, { "input": "realDonaldTrump", "state": "added" } ], "summary": { "failed": 0, "succeeded": 2, "total": 2 } } ``` ##### Remove result ```json { "action": "unfollow", "requestId": "3f1c7d2e-5a4b-4c8d-9e0f-1a2b3c4d5e6f", "error": null, "results": [ { "input": "marketdesk", "state": "removed" } ], "summary": { "failed": 0, "succeeded": 1, "total": 1 } } ``` ### Route an account to Discord and filter keywords Change one tracked account's Discord webhook and keyword filters from your backend. The dashboard edits the same settings. #### Send the changes Send the tracked handle as `account`; a leading @ is optional. Include `discordWebhook`, `keywords`, or both; an omitted field keeps its saved value. Success returns `{ account, discordWebhook, keywords }`. - [`PATCH /api/account-settings`](https://tweetstream.io/docs/api/update-account-settings.md) - `discordWebhook` must be a `https://discord.com/api/webhooks/...` or `https://discordapp.com/api/webhooks/...` URL. This account's Discord alerts go there instead of your global webhook, unless a Discord bot channel is connected, which receives every alert. Send `null` to use the global webhook again. - `keywords` replaces the account's list. A post from this account whose text contains any keyword, ignoring case, is skipped on WebSocket and Discord. Send `[]` to clear it. ##### Change account settings ```typescript const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY"); const response = await fetch("https://api.tweetstream.io/api/account-settings", { method: "PATCH", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ account: "marketdesk", discordWebhook: process.env.MARKETDESK_DISCORD_WEBHOOK, keywords: ["giveaway", "airdrop"], }), }); if (!response.ok) { const detail = await response.text(); throw new Error(`Settings update failed (${response.status}): ${detail}`); } console.log(await response.json()); ``` #### Handle setting errors | Status | When it appears | Action | | --- | --- | --- | | `200` | The settings are saved | Read the saved values | | `400` | The body is invalid, has neither field, or the webhook is not a Discord webhook | Fix the request | | `401` | The bearer key is missing or invalid | Send a valid API key | | `403` | The subscription is inactive | Check plan access | | `404` | The handle is not tracked on this account | Add the account first | ### Check current usage Call `/api/me` with either the standard or Ultra API key. The private response is not cached. - [`GET /api/me`](https://tweetstream.io/docs/api/get-account-status.md) #### Read plan and usage fields The response contains base-plan usage and any additive Ultra Speed details. | Field | Type | Notes | | --- | --- | --- | | `credentialScope` | `standard` or `ultra_speed` | Scope of the bearer key used | | `plan` | `BASIC`, `ELITE`, or `ENTERPRISE` | Runtime plan value: `BASIC` is Minimum, `ELITE` is Pro, and `ENTERPRISE` is Scale | | `trackedAccounts` | object | Count, limit, and normalized handles | | `websocket` | object | Current active connection count and plan limit | | `stripe` | object | Subscription status and billing period fields; treat identifiers as private | | `ultraSpeed` | `object` or `null` | Ultra status, billing cycle, limits, tracked handles (can repeat top-level `trackedAccounts` handles), scoped WebSocket usage, and cancellation timing | #### Inspect the response ##### Account usage request ```typescript const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY"); const response = await fetch("https://api.tweetstream.io/api/me", { headers: { Authorization: `Bearer ${apiKey}`, }, }); if (!response.ok) { const detail = await response.text(); throw new Error(`Account status failed (${response.status}): ${detail}`); } console.log(await response.json()); ``` ##### Account usage response ```json { "credentialScope": "standard", "plan": "ELITE", "trackedAccounts": { "count": 2, "limit": 250, "handles": ["marketdesk", "realDonaldTrump"] }, "websocket": { "count": 1, "limit": 10 }, "stripe": { "subscriptionStatus": "ACTIVE", "customerId": "[redacted]", "hasCustomer": true, "subscriptionId": "[redacted]", "currentPeriodStart": "2026-06-30T00:00:00.000Z", "currentPeriodEnd": "2026-07-30T00:00:00.000Z", "canceledAt": null }, "ultraSpeed": { "active": true, "status": "ACTIVE", "billingCycle": "MONTHLY", "paymentRail": "STRIPE_CARD", "accountLimit": 25, "trackedAccounts": { "count": 1, "handles": ["realDonaldTrump"] }, "websocket": { "count": 1, "limit": 5 }, "currentPeriodEnd": "2026-07-30T00:00:00.000Z", "cancelAtPeriodEnd": false, "canceledAt": null } } ``` ### Track affiliate list changes Affiliate list changes are off by default for tracked business accounts on active or trialing Pro, Scale, and Ultra plans. #### Enable or disable alerts Use `POST /api/affiliate-alerts`, `DELETE /api/affiliate-alerts`, or the dashboard. Send the tracked handle as `account`; a leading @ is optional. Repeating a request is safe. Success returns `{ account, affiliateAlertsEnabled }`. - [`POST /api/affiliate-alerts`](https://tweetstream.io/docs/api/enable-affiliate-alerts.md) - [`DELETE /api/affiliate-alerts`](https://tweetstream.io/docs/api/disable-affiliate-alerts.md) ##### Change the alert setting ```typescript async function setAffiliateAlerts(account: string, enabled: boolean) { const response = await fetch("https://api.tweetstream.io/api/affiliate-alerts", { method: enabled ? "POST" : "DELETE", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ account }), }); if (!response.ok) { throw new Error(await response.text()); } return await response.json(); } console.log(await setAffiliateAlerts("marketdesk", true)); console.log(await setAffiliateAlerts("marketdesk", false)); ``` #### Handle setting errors When enabling alerts, TweetStream checks that the account still qualifies as a business account. A failed check returns `400` with `{ error: "This account is not a business account." }`. | Status | When it appears | Action | | --- | --- | --- | | `200` | The saved setting matches the request | Read `affiliateAlertsEnabled` | | `400` | The body is invalid or the account is not a business account | Fix the request | | `401` | The bearer key is missing or invalid | Send a valid API key | | `403` | The subscription or feature access is inactive | Check plan access | | `404` | The handle is not tracked by this API key | Check the tracked handle | | `500` | TweetStream could not confirm eligibility | Retry later | #### Store and replay changes Changes go to WebSocket, the dashboard feed, and your Discord route. Keyword filters do not apply. Store relationships by `(organization.id, member.id)` and use `eventId` only for exact replay deduplication. Replay recorded changes with `GET /api/history?type=AFFILIATE`. There is no current-list snapshot or pre-feature backfill. ### Stream Binance Square posts Binance Square accounts are off by default. Enable them in the dashboard or through this API. They remain separate from tracked X accounts and do not use an X account slot. #### List and change settings `GET /api/binance-square` returns saved settings and the catalog fields `displayName`, `squareHandle`, `profileUrl`, `avatarUrl`, and `enabled`. `POST /api/binance-square` enables an account; `DELETE /api/binance-square` disables it. Send the Square handle in `account`; a leading @ is optional. Repeating a request is safe. - [`GET /api/binance-square`](https://tweetstream.io/docs/api/list-binance-square-accounts.md) - [`POST /api/binance-square`](https://tweetstream.io/docs/api/enable-binance-square-account.md) - [`DELETE /api/binance-square`](https://tweetstream.io/docs/api/disable-binance-square-account.md) - `profileUrl` is canonical. `avatarUrl` is `null` when unavailable. - Settings belong to your TweetStream user, so active Standard and Ultra credentials share them. - A saved response returns `{ account, binanceSquareEnabled }` with the canonical handle. ##### List Binance Square accounts ```typescript const response = await fetch( "https://api.tweetstream.io/api/binance-square", { headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }, ); if (!response.ok) { throw new Error(await response.text()); } const catalog = await response.json(); console.log(catalog); // { // accounts: [{ // avatarUrl: "https://bin.bnbstatic.com/static/content/live-admin-api/images/chVikg58jFQ6ScXcVmWNmj.png", // displayName: "币安Binance华语", // enabled: true, // profileUrl: "https://www.binance.com/en/square/profile/Vpo7Qwqy63rk7_Km3zYYaQ", // squareHandle: "binancezh" // }], // canManage: true // } ``` ##### Enable or disable posts ```typescript async function setBinanceSquarePosts(account: string, enabled: boolean) { const response = await fetch("https://api.tweetstream.io/api/binance-square", { method: enabled ? "POST" : "DELETE", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ account }), }); if (!response.ok) { throw new Error(await response.text()); } return await response.json(); } console.log(await setBinanceSquarePosts("binancezh", true)); // { account: "binancezh", binanceSquareEnabled: true } ``` #### Handle live content Enabled accounts send live posts, replies, and quotes over WebSocket and applicable Discord routes. History does not store Square content, so reconnects do not backfill missed posts. Keyword filters still apply. Discord uses the global webhook unless an account-specific route applies. - Content uses `tweet/content`, with `author.platform` set to `binance_square` and `kind` set to `post`, `reply`, or `quote`. - Later tweet operations set `d.platform` to `binance_square`; use `(platform, tweetId)` as the post key. - Replies and quotes include `ref` when reference context is available. Post links use canonical Binance URLs. Square authors have no `author.url`, since Square does not report an account website. ##### Binance Square content event ```json { "v": 1, "t": "tweet", "op": "content", "id": "358051617962575", "ts": 1772000001100, "d": { "tweetId": "358051617962575", "kind": "quote", "text": "Example Binance Square quote", "createdAt": 1772000001000, "receivedAt": 1772000001100, "link": "https://www.binance.com/en/square/post/358051617962575", "author": { "id": "Vpo7Qwqy63rk7_Km3zYYaQ", "handle": "@binancezh", "platform": "binance_square" }, "ref": { "type": "quote", "tweetId": "358012920288073" } } } ``` #### Handle setting errors | Status | When it appears | Action | | --- | --- | --- | | `200` | The catalog was listed or the setting was saved | Read the response body | | `400` | The body is invalid or the account is not in the catalog | Fix the request | | `401` | The bearer key is missing or invalid | Send a valid API key | | `403` | The API credential is not active | Check subscription status | | `500` | TweetStream could not save the setting | Retry later | ### Read handle result states | State | When it appears | Recommended handling | | --- | --- | --- | | `added` | Handle was added to the watchlist | Treat as success | | `already_following` | Handle is already tracked | Treat as idempotent at the row level | | `removed` | Handle was removed | Treat as success | | `not_following` | Handle was not tracked | Treat as idempotent at the row level | | `invalid_input`, `duplicate`, `not_found`, `failed` | Invalid input, duplicate input, missing account, or operation failure | Show the row-level message and retry only when appropriate | ### Read REST status codes Add and remove endpoints return one result per handle. The HTTP status describes the batch; each result row describes its handle. | Status | When it appears | Notes | | --- | --- | --- | | `200` | No row failed, including idempotent success rows | `summary.failed` is 0; `already_following` and `not_following` are successful outcomes | | `207` | Some rows succeeded and some rows failed | Read each `results` row before retrying | | `400` | The request body is invalid or every row failed for a non-temporary reason | Fix the request or row-level errors before retrying | | `429` | Too many handle requests | Wait, then retry the batch | | `503` | Every row failed for a temporary reason | Retry the batch with backoff | ### Check plan limits - Minimum: 50 monitored accounts and 3 WebSocket connections after trial. - Trial: 5 monitored accounts and 1 WebSocket connection for 3 days. - Pro: 250 monitored accounts and 10 WebSocket connections. - Scale: self-serve higher monitored-account and WebSocket limits from the pricing page. - History replay is available on Pro, Scale, and Ultra Speed. ## Complete WebSocket example Copy one TypeScript or Python program, run it with your API key, and watch it connect, reconnect, merge tweet updates, follow reference chains, and time each post. Canonical URL: https://tweetstream.io/docs/examples > Using an AI coding agent? > > Point it at this page's Markdown and the protocol specs, and ask it to follow these rules: > > 1. Key every post by `(platform, tweetId)`. > 2. Merge `tweet/update` fields over the stored content. An update carries only the fields it changes. > 3. When an update carries `ref`, replace the stored `ref` and follow `ref.subtweet` for the rest of the chain. > 4. Treat each `tweet/meta` as a full snapshot and replace the stored `meta` with it. > 5. Skip any `t` and `op` pair you don't handle and keep the socket open. > > - [This page as Markdown](https://tweetstream.io/docs/examples.md) > - [AsyncAPI spec](https://tweetstream.io/docs/asyncapi.json) > - [OpenAPI spec](https://tweetstream.io/docs/openapi.json) ### Run it Replace `YOUR_API_KEY` with the key from your dashboard. A trial key works. Posts arrive when a monitored account posts, so add at least one account in the dashboard or set `TWEETSTREAM_ACCOUNTS`. #### TypeScript Needs Node.js 22.18 or later, which runs TypeScript files directly. The program has no dependencies. 1. Copy the program ```typescript // TweetStream complete example: connect, reconnect, handle every event, and measure latency. // Node.js 22.18 or later runs this TypeScript file directly. No dependencies. // // TWEETSTREAM_API_KEY=YOUR_API_KEY node tweetstream-example.ts // // Optional settings: // TWEETSTREAM_ACCOUNTS=handle1,handle2 add these accounts before connecting // TWEETSTREAM_WS_URL=wss://ws-iad.tweetstream.io/ws use the US endpoint // The messages this program reads, limited to the fields it uses. Every field of every event: // https://tweetstream.io/docs/asyncapi.json // Every server message is a v1 envelope. Route on t (channel) and op (operation); d is the payload. type Envelope = { v: 1; t: string; op: string; id?: string; ts: number; d: unknown }; // Posts name their author by handle. Some account events use username instead. type Account = { id?: string; handle?: string; username?: string; platform?: string }; type PostKind = "post" | "quote" | "reply" | "retweet"; // A post that this one quotes, replies to, or reposts. It can reference another through subtweet. type Reference = { type: Exclude; tweetId?: string; author?: Account; text?: string; subtweet?: Reference; }; // tweet/content: a new post. author.platform is "twitter" when it is missing. type PostContent = { tweetId: string; text: string; createdAt: number; // Unix milliseconds kind: PostKind; author: Account; ref?: Reference; // The post a reply also quotes. quoted?: Reference; }; // tweet/update: only the fields that changed. textUpdateType "completion" delivers the full text // of a post that arrived shortened; it is not an edit. type PostUpdate = Partial> & { tweetId: string; platform?: string; textUpdateType?: "completion"; }; // tweet/meta: a complete snapshot of the tokens, markets, and image text found in a post. type PostMeta = { tweetId: string; platform?: string; detected?: { tokens?: Array<{ symbol?: string; contract?: string; priceUsd?: number }>; prediction?: Array<{ title?: string; priceUsd?: number }>; }; ocr?: { text: string }; }; // tweet/delete, tweet/pin, and tweet/unpin. type PostEvent = { tweetId: string; platform?: string; author?: Account }; type Coin = { symbol?: string; address?: string }; // The payload of each t/op pair this program handles. type Payloads = { "control/auth_pong": Record; "tweet/content": PostContent; "tweet/update": PostUpdate; "tweet/meta": PostMeta; "tweet/delete": PostEvent; "tweet/pin": PostEvent; "tweet/unpin": PostEvent; "account/follow": { actor: Account; target: Account }; "account/unfollow": { actor: Account; target: Account }; "account/profile_update": { actor: Account; changes: Record }; "account/affiliate_update": { organization: Account; member: Account; action: string }; "account/callout": { caller: Account; token: Coin }; "account/callout_update": { updateOf: string; token?: Coin }; "account/perp_callout": { caller: Account; market: { venue: string; symbol: string; side: string; leverage: string }; }; "account/thesis": { author: Account; coin: Coin; thesis: { text: string } }; "account/token_verified": { coin: Coin }; "news/article": { source?: { name?: string }; title?: string }; "charity/added": { name: string }; "control/twitter_handles_result": { results: Array<{ input: string; state: string }>; error: string | null; }; }; type Pair = keyof Payloads; type Handler

= (d: P, receivedAt: number) => void; // What this program keeps for each post. type StoredPost = { content: Partial | null; meta: PostMeta | null; deleted: boolean; pinned: boolean; hasContent: boolean; }; const API_KEY = process.env.TWEETSTREAM_API_KEY?.trim(); const DASHBOARD = "https://tweetstream.io/dashboard?tab=api"; if (!API_KEY) { console.error(`Set TWEETSTREAM_API_KEY. Copy your key from ${DASHBOARD}`); process.exit(1); } const WS_URL = process.env.TWEETSTREAM_WS_URL || "wss://ws-global.tweetstream.io/ws"; const API_URL = "https://api.tweetstream.io"; const ACCOUNTS = (process.env.TWEETSTREAM_ACCOUNTS ?? "") .split(",") .map((handle) => handle.trim().replace(/^@/, "")) .filter(Boolean); const TWITTER_EPOCH_MS = 1288834974657n; const posts = new Map(); // "platform:tweetId" -> stored post const counts = new Map(); // "t/op" -> number of events seen const latencies: number[] = []; // publish-to-receipt ms for the most recent 10,000 new posts let attempt = 0; let hinted = false; const log = (label: string, text: string) => console.log(`${label.padEnd(9)} ${text}`); const at = (account: Account | undefined) => `@${String(account?.handle ?? account?.username ?? "unknown").replace(/^@/, "")}`; const clip = (text: unknown, max = 80) => { const flat = String(text ?? "").replace(/\s+/g, " ").trim(); return JSON.stringify(flat.length > max ? `${flat.slice(0, max - 1)}…` : flat); }; // Posts are keyed by (platform, tweetId). Content carries the platform on its author; // later operations carry it on d.platform. const platformOf = (d: PostEvent) => d.platform ?? d.author?.platform ?? "twitter"; function postFor(d: PostEvent, platform = platformOf(d)): StoredPost { const key = `${platform}:${d.tweetId}`; let post = posts.get(key); if (!post) { post = { content: null, deleted: false, hasContent: false, meta: null, pinned: false }; posts.set(key, post); if (posts.size > 10_000) { const oldest = posts.keys().next().value; if (oldest !== undefined) posts.delete(oldest); // bound memory } } return post; } // Updates carry only the fields that changed, so merge them over what you stored. const merge = (base: Partial | null, patch: Partial | null) => ({ ...base, ...patch, author: { ...base?.author, ...patch?.author }, }); function publishedAtMs(platform: string, d: PostContent): number | null { // X post IDs encode their publish time: (id >> 22) + the Twitter epoch. if (platform === "twitter" && /^\d+$/.test(d.tweetId)) { return Number((BigInt(d.tweetId) >> 22n) + TWITTER_EPOCH_MS); } return typeof d.createdAt === "number" ? d.createdAt : null; } function referenceChain(ref: Reference | undefined): string { const links: string[] = []; // A referenced post can reference another one through ref.subtweet. for (let r = ref, depth = 0; r && depth < 8; r = r.subtweet, depth++) { // A reference can name only its author until an update adds its ID and text. const parts = [r.type ?? "ref", at(r.author), r.tweetId, r.text ? clip(r.text, 40) : undefined]; links.push(parts.filter(Boolean).join(" ")); } return links.join(" -> "); } function describeMeta(meta: PostMeta): string { const price = (value: number | undefined, prefix = "") => (value == null ? "" : ` ${prefix}${value}`); const tokens = meta.detected?.tokens ?? []; const markets = meta.detected?.prediction ?? []; const parts: string[] = []; if (tokens.length) { parts.push(`tokens ${tokens.map((t) => `${t.symbol ?? t.contract}${price(t.priceUsd, "$")}`).join(", ")}`); } if (markets.length) { parts.push(`markets ${markets.map((m) => `${clip(m.title, 40)}${price(m.priceUsd)}`).join(", ")}`); } if (meta.ocr?.text) parts.push(`ocr ${clip(meta.ocr.text, 40)}`); return parts.join(" | ") || "no detections"; } // Delete, pin, and unpin change the stored post's state and keep its content. function lifecycle(d: PostEvent, label: string, change: Partial) { Object.assign(postFor(d), change); log(label, `${at(d.author)} ${d.tweetId}`); } const handlers: { [P in Pair]: Handler } = { "control/auth_pong": () => log("auth", "ok, waiting for events"), "tweet/content": (d, receivedAt) => { const platform = d.author?.platform ?? "twitter"; const post = postFor(d, platform); post.content = merge(d, post.content); // an update that arrived first still wins let latency = ""; const publishedAt = publishedAtMs(platform, d); if (!post.hasContent && publishedAt !== null) { latencies.push(receivedAt - publishedAt); if (latencies.length > 10_000) latencies.shift(); latency = `${receivedAt - publishedAt} ms `; } post.hasContent = true; const where = platform === "twitter" ? "" : ` (${platform})`; log("post", `${at(d.author)}${where} ${d.tweetId} ${latency}${clip(post.content.text)}`); if (d.ref) log("", `chain: ${referenceChain(d.ref)}`); if (d.quoted) log("", `quoted: ${referenceChain(d.quoted)}`); }, "tweet/update": (d) => { const post = postFor(d); post.content = merge(post.content, d); // a ref or quoted in the update replaces the stored one const who = `${at(post.content.author)} ${d.tweetId}`; const changed = Object.keys(d).filter((k) => !["platform", "receivedAt", "tweetId"].includes(k)); if (d.ref) log("update", `${who} chain: ${referenceChain(d.ref)}`); if (d.quoted) log("update", `${who} quoted: ${referenceChain(d.quoted)}`); if (d.ref || d.quoted) return; if (d.textUpdateType === "completion") log("update", `${who} full text ${clip(d.text)}`); else log("update", `${who} changed ${changed.join(", ")}`); }, "tweet/meta": (d) => { const post = postFor(d); post.meta = d; // each meta is a complete snapshot: replace it, never merge log("meta", `${at(post.content?.author)} ${d.tweetId} ${describeMeta(d)}`); }, "tweet/delete": (d) => lifecycle(d, "delete", { deleted: true }), "tweet/pin": (d) => lifecycle(d, "pin", { pinned: true }), "tweet/unpin": (d) => lifecycle(d, "unpin", { pinned: false }), "account/follow": (d) => log("follow", `${at(d.actor)} followed ${at(d.target)}`), "account/unfollow": (d) => log("unfollow", `${at(d.actor)} unfollowed ${at(d.target)}`), "account/profile_update": (d) => log("profile", `${at(d.actor)} changed ${Object.keys(d.changes ?? {}).join(", ")}`), "account/affiliate_update": (d) => log("affiliate", `${at(d.organization)} ${d.action} ${at(d.member)}`), "account/callout": (d) => log("callout", `${at(d.caller)} called ${d.token?.symbol} ${d.token?.address}`), "account/callout_update": (d) => log("callout", `update to ${d.updateOf}: ${d.token?.symbol}`), "account/perp_callout": (d) => log("perp", `${at(d.caller)} ${d.market?.side} ${d.market?.symbol} ${d.market?.leverage}x on ${d.market?.venue}`), "account/thesis": (d) => log("thesis", `${at(d.author)} on ${d.coin?.symbol}: ${clip(d.thesis?.text, 60)}`), "account/token_verified": (d) => log("verified", `${d.coin?.symbol ?? d.coin?.address}`), "news/article": (d) => log("news", `${d.source?.name}: ${clip(d.title)}`), "charity/added": (d) => log("charity", d.name), "control/twitter_handles_result": (d) => log("handles", (d.results ?? []).map((r) => `${r.input} ${r.state}`).join(", ") || String(d.error)), }; const isPair = (pair: string): pair is Pair => Object.hasOwn(handlers, pair); function onMessage(data: unknown, receivedAt: number) { let event: Partial | null; try { event = JSON.parse(String(data)); } catch { log("skip", "frame is not JSON"); return; } if (event?.v !== 1 || typeof event.t !== "string" || typeof event.op !== "string") return; const pair = `${event.t}/${event.op}`; counts.set(pair, (counts.get(pair) ?? 0) + 1); if (!isPair(pair)) return; // unknown pairs are counted, then ignored // The payload is JSON from the server; the types above describe what each pair carries. const handle = handlers[pair] as Handler; try { handle(event.d ?? {}, receivedAt); } catch (error) { log("error", `${pair}: ${error}`); // one malformed event must not stop the program } } function printSummary() { const sorted = [...latencies].sort((a, b) => a - b); const pct = (p: number) => sorted[Math.max(0, Math.ceil(p * sorted.length) - 1)]; const timing = sorted.length ? `p50 ${pct(0.5)} ms p95 ${pct(0.95)} ms (n=${sorted.length})` : "no posts yet"; const seen = [...counts].map(([pair, n]) => `${pair} ${n}`).join(", ") || "none"; log("summary", `latency ${timing} | events ${seen}`); } // POST /api/add-account answers with one row per handle. type AddAccountResponse = { results?: Array<{ input: string; state: string; message?: string }>; error?: string; }; async function addAccounts() { const response = await fetch(`${API_URL}/api/add-account`, { body: JSON.stringify({ accounts: ACCOUNTS }), headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" }, method: "POST", signal: AbortSignal.timeout(15_000), }); const body = (await response.json().catch(() => ({}))) as AddAccountResponse; // One row per handle, even on 207 (some failed) or 400 (all failed). Each row says why. const rows = Array.isArray(body.results) ? body.results : []; for (const row of rows) { log("accounts", `${row.input} ${row.state}${row.message ? `: ${row.message}` : ""}`); } if (!rows.length && !response.ok) { log("accounts", `add failed (${response.status}): ${body.error ?? "unknown error"}`); } } // GET /api/me reports which pool the key connects to and how many connections each has open. type ConnectionPool = { count: number; limit: number }; type MeResponse = { credentialScope?: "standard" | "ultra_speed"; websocket?: ConnectionPool; // standard keys ultraSpeed?: { websocket?: ConnectionPool } | null; // Ultra Speed keys }; async function explainRefusedConnection() { // Node's built-in WebSocket hides the HTTP status of a refused upgrade, so ask the REST API. const headers = { Authorization: `Bearer ${API_KEY}` }; const response = await fetch(`${API_URL}/api/me`, { headers, signal: AbortSignal.timeout(10_000), }).catch(() => null); if (response?.status === 401) { console.error(`API key rejected (401). Copy a current key from ${DASHBOARD}`); process.exit(1); } if (response?.status === 403) { console.error("Streaming is not active for this key (403). Start a trial or renew your plan."); process.exit(1); } const me = (response?.ok ? await response.json().catch(() => null) : null) as MeResponse | null; const pool = me?.credentialScope === "ultra_speed" ? me.ultraSpeed?.websocket : me?.websocket; if (pool && pool.count >= pool.limit) { log("limit", `all ${pool.limit} connections are in use; close another client`); } } function connect() { const socket = new WebSocket(WS_URL, ["tweetstream.v1", `tweetstream.auth.token.${API_KEY}`]); let openedAt: number | null = null; // set while this socket is open socket.addEventListener("open", () => { openedAt = Date.now(); log("connected", WS_URL); socket.send(JSON.stringify({ op: "auth_ping" })); // answered by control/auth_pong setTimeout(() => { if (openedAt !== null && !latencies.length && !hinted) { hinted = true; log("hint", "posts appear when a monitored account posts. Add accounts in the"); log("hint", "dashboard, or run again with TWEETSTREAM_ACCOUNTS=handle1,handle2"); } }, 120_000); }); // Take the receipt time before any parsing so latency excludes your own processing. socket.addEventListener("message", (event) => onMessage(event.data, Date.now())); let settled = false; // some runtimes fire both error and close; reconnect only once const reconnect = async (reason: string) => { if (settled) return; settled = true; if (openedAt === null) await explainRefusedConnection(); else if (Date.now() - openedAt >= 30_000) attempt = 0; // healthy session: reset backoff openedAt = null; const delay = Math.min(30_000, 1_000 * 2 ** attempt) + Math.floor(Math.random() * 250); attempt = Math.min(attempt + 1, 5); log("closed", `${reason}; reconnecting in ${(delay / 1000).toFixed(1)} s`); setTimeout(connect, delay); }; // Node's built-in WebSocket reports a refused or failed handshake with error and no close. socket.addEventListener("error", () => openedAt === null && reconnect("connection failed")); socket.addEventListener("close", (event) => reconnect(`code ${event.code}`)); } process.on("SIGINT", () => { printSummary(); process.exit(0); }); setInterval(printSummary, 60_000); if (ACCOUNTS.length) { addAccounts() .catch((error: Error) => log("accounts", `add failed: ${error.message}`)) .finally(connect); } else { connect(); } ``` 2. Save it as `tweetstream-example.ts` 3. Run it with your key ```bash TWEETSTREAM_API_KEY=YOUR_API_KEY node tweetstream-example.ts ``` [Raw file: tweetstream-example.ts](https://tweetstream.io/docs/examples/tweetstream-example.ts) #### Python Needs Python 3.10 or later. The run command creates a virtual environment and installs `websockets` into it. 1. Copy the program ```python """TweetStream complete example: connect, reconnect, handle every event, and measure latency. Python 3.10 or later. One dependency, installed in a virtual environment: python3 -m venv tweetstream-venv tweetstream-venv/bin/pip install 'websockets>=14' TWEETSTREAM_API_KEY=YOUR_API_KEY tweetstream-venv/bin/python tweetstream_example.py Optional settings: TWEETSTREAM_ACCOUNTS=handle1,handle2 add these accounts before connecting TWEETSTREAM_WS_URL=wss://ws-iad.tweetstream.io/ws use the US endpoint """ import asyncio import collections import json import math import os import random import sys import time import urllib.error import urllib.request if sys.version_info < (3, 10): sys.exit(f"This example needs Python 3.10 or later; this is {sys.version.split()[0]}.") import websockets API_KEY = os.environ.get("TWEETSTREAM_API_KEY", "").strip() DASHBOARD = "https://tweetstream.io/dashboard?tab=api" if not API_KEY: sys.exit(f"Set TWEETSTREAM_API_KEY. Copy your key from {DASHBOARD}") WS_URL = os.environ.get("TWEETSTREAM_WS_URL") or "wss://ws-global.tweetstream.io/ws" API_URL = "https://api.tweetstream.io" ACCOUNTS = [ handle.strip().lstrip("@") for handle in os.environ.get("TWEETSTREAM_ACCOUNTS", "").split(",") if handle.strip() ] TWITTER_EPOCH_MS = 1288834974657 posts = {} # (platform, tweetId) -> {"content", "meta", "deleted", "pinned", "has_content"} counts = {} # "t/op" -> number of events seen latencies = collections.deque(maxlen=10_000) # publish-to-receipt ms, most recent new posts hinted = False def log(label, text): print(f"{label:<9} {text}", flush=True) def at(account): account = account if isinstance(account, dict) else {} return "@" + str(account.get("handle") or account.get("username") or "unknown").lstrip("@") def clip(text, limit=80): flat = " ".join(str(text or "").split()) return json.dumps(flat if len(flat) <= limit else flat[: limit - 1] + "…", ensure_ascii=False) def field(d, name, key): return (d.get(name) or {}).get(key) # Posts are keyed by (platform, tweetId). Content carries the platform on its author; # later operations carry it on d.platform. def post_for(d, platform=None): platform = platform or d.get("platform") or field(d, "author", "platform") or "twitter" key = (platform, d["tweetId"]) if key not in posts: posts[key] = {"content": None, "meta": None, "deleted": False, "pinned": False} posts[key]["has_content"] = False if len(posts) > 10_000: posts.pop(next(iter(posts))) # bound memory return posts[key] def merge(base, patch): # Updates carry only the fields that changed, so merge them over what you stored. base, patch = base or {}, patch or {} return {**base, **patch, "author": {**(base.get("author") or {}), **(patch.get("author") or {})}} def published_at_ms(platform, d): tweet_id = str(d.get("tweetId", "")) if platform == "twitter" and tweet_id.isdigit(): return (int(tweet_id) >> 22) + TWITTER_EPOCH_MS # X post IDs encode their publish time created_at = d.get("createdAt") return created_at if isinstance(created_at, (int, float)) else None def reference_chain(ref): links = [] # A referenced post can reference another one through subtweet. while ref and len(links) < 8: # A reference can name only its author until an update adds its ID and text. text = clip(ref["text"], 40) if ref.get("text") else None parts = [ref.get("type", "ref"), at(ref.get("author")), ref.get("tweetId"), text] links.append(" ".join(part for part in parts if part)) ref = ref.get("subtweet") return " -> ".join(links) def describe_meta(meta): detected = meta.get("detected") or {} tokens = [t.get("symbol") or t.get("contract") for t in detected.get("tokens") or []] prices = [t.get("priceUsd") for t in detected.get("tokens") or []] markets = [clip(m.get("title"), 40) for m in detected.get("prediction") or []] odds = [m.get("priceUsd") for m in detected.get("prediction") or []] parts = [] if tokens: parts.append("tokens " + ", ".join(t if p is None else f"{t} ${p}" for t, p in zip(tokens, prices))) if markets: parts.append("markets " + ", ".join(m if p is None else f"{m} {p}" for m, p in zip(markets, odds))) if field(meta, "ocr", "text"): parts.append(f"ocr {clip(meta['ocr']['text'], 40)}") return " | ".join(parts) or "no detections" def on_content(d, received_at): platform = field(d, "author", "platform") or "twitter" post = post_for(d, platform) post["content"] = merge(d, post["content"]) # an update that arrived first still wins latency = "" published_at = published_at_ms(platform, d) if not post["has_content"] and published_at is not None: latencies.append(round(received_at - published_at)) latency = f"{latencies[-1]} ms " post["has_content"] = True where = "" if platform == "twitter" else f" ({platform})" text = clip(post["content"].get("text")) log("post", f"{at(d.get('author'))}{where} {d['tweetId']} {latency}{text}") if d.get("ref"): log("", f"chain: {reference_chain(d['ref'])}") if d.get("quoted"): # the post a reply also quotes log("", f"quoted: {reference_chain(d['quoted'])}") def on_update(d, _): post = post_for(d) post["content"] = merge(post["content"], d) # a ref or quoted in the update replaces the stored one who = f"{at(post['content'].get('author'))} {d['tweetId']}" changed = ", ".join(k for k in d if k not in ("platform", "receivedAt", "tweetId")) if d.get("ref"): log("update", f"{who} chain: {reference_chain(d['ref'])}") if d.get("quoted"): log("update", f"{who} quoted: {reference_chain(d['quoted'])}") if d.get("ref") or d.get("quoted"): return if d.get("textUpdateType") == "completion": log("update", f"{who} full text {clip(d.get('text'))}") else: log("update", f"{who} changed {changed}") def on_meta(d, _): post = post_for(d) post["meta"] = d # each meta is a complete snapshot: replace it, never merge log("meta", f"{at((post['content'] or {}).get('author'))} {d['tweetId']} {describe_meta(d)}") def lifecycle(label, **change): # Delete, pin, and unpin change the stored post's state and keep its content. def handle(d, _): post_for(d).update(change) log(label, f"{at(d.get('author'))} {d['tweetId']}") return handle HANDLERS = { "tweet/content": on_content, "tweet/update": on_update, "tweet/meta": on_meta, "tweet/delete": lifecycle("delete", deleted=True), "tweet/pin": lifecycle("pin", pinned=True), "tweet/unpin": lifecycle("unpin", pinned=False), } def event_line(pair, d): # One readable line for account, news, charity, and control events. actor, target = at(d.get("actor")), at(d.get("target")) token, coin, market = d.get("token") or {}, d.get("coin") or {}, d.get("market") or {} results = ", ".join(f"{r.get('input')} {r.get('state')}" for r in d.get("results") or []) return { "control/auth_pong": ("auth", "ok, waiting for events"), "control/twitter_handles_result": ("handles", results or str(d.get("error"))), "account/follow": ("follow", f"{actor} followed {target}"), "account/unfollow": ("unfollow", f"{actor} unfollowed {target}"), "account/profile_update": ("profile", f"{actor} changed {', '.join(d.get('changes') or {})}"), "account/affiliate_update": ( "affiliate", f"{at(d.get('organization'))} {d.get('action')} {at(d.get('member'))}", ), "account/callout": ( "callout", f"{at(d.get('caller'))} called {token.get('symbol')} {token.get('address')}", ), "account/callout_update": ("callout", f"update to {d.get('updateOf')}: {token.get('symbol')}"), "account/perp_callout": ( "perp", f"{at(d.get('caller'))} {market.get('side')} {market.get('symbol')} {market.get('leverage')}x on {market.get('venue')}", ), "account/thesis": ( "thesis", f"{at(d.get('author'))} on {coin.get('symbol')}: {clip(field(d, 'thesis', 'text'), 60)}", ), "account/token_verified": ("verified", coin.get("symbol") or coin.get("address")), "news/article": ("news", f"{field(d, 'source', 'name')}: {clip(d.get('title'))}"), "charity/added": ("charity", d.get("name")), }.get(pair) def on_message(raw, received_at): try: event = json.loads(raw) except ValueError: return log("skip", "frame is not JSON") # Envelope: {v, t, op, id?, ts, d}. Route by t, then op. if not isinstance(event, dict) or event.get("v") != 1: return pair = f"{event.get('t')}/{event.get('op')}" counts[pair] = counts.get(pair, 0) + 1 d = event.get("d") or {} try: if pair in HANDLERS: HANDLERS[pair](d, received_at) elif event_line(pair, d): # unknown pairs are counted, then ignored log(*event_line(pair, d)) except Exception as error: # one malformed event must not close the connection log("error", f"{pair}: {error!r}") def print_summary(): ordered = sorted(latencies) pct = lambda p: ordered[max(0, math.ceil(p * len(ordered)) - 1)] timing = f"p50 {pct(0.5)} ms p95 {pct(0.95)} ms (n={len(ordered)})" if ordered else "no posts yet" seen = ", ".join(f"{pair} {n}" for pair, n in counts.items()) or "none" log("summary", f"latency {timing} | events {seen}") def add_accounts(): request = urllib.request.Request( f"{API_URL}/api/add-account", data=json.dumps({"accounts": ACCOUNTS}).encode(), headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}, method="POST", ) try: with urllib.request.urlopen(request, timeout=15) as response: status, raw = response.status, response.read() except urllib.error.HTTPError as error: # 400, 429, and 503 can still carry results status, raw = error.code, error.read() except OSError as error: return log("accounts", f"add failed: {error}") try: body = json.loads(raw) except ValueError: body = {} body = body if isinstance(body, dict) else {} # One row per handle, even on 207 (some failed) or 400 (all failed). Each row says why. rows = body.get("results") if isinstance(body.get("results"), list) else [] for row in rows: message = f": {row['message']}" if row.get("message") else "" log("accounts", f"{row.get('input')} {row.get('state')}{message}") if not rows and status >= 300: log("accounts", f"add failed ({status}): {body.get('error') or 'unknown error'}") async def report_every_minute(): while True: await asyncio.sleep(60) print_summary() async def hint_when_quiet(): global hinted await asyncio.sleep(120) if not latencies and not hinted: hinted = True log("hint", "posts appear when a monitored account posts. Add accounts in the") log("hint", "dashboard, or run again with TWEETSTREAM_ACCOUNTS=handle1,handle2") async def main(): asyncio.create_task(report_every_minute()) protocols = ["tweetstream.v1", f"tweetstream.auth.token.{API_KEY}"] attempt = 0 while True: opened_at, reason = None, "connection closed" try: async with websockets.connect(WS_URL, subprotocols=protocols) as ws: opened_at = time.monotonic() log("connected", WS_URL) await ws.send(json.dumps({"op": "auth_ping"})) # answered by control/auth_pong hint = asyncio.create_task(hint_when_quiet()) try: async for raw in ws: # Take the receipt time before parsing so latency excludes your own work. on_message(raw, time.time() * 1000) finally: hint.cancel() except Exception as error: # A refused upgrade carries its HTTP status on error.response. 429 means the pool # this key connects to (standard or Ultra Speed) has no free connection. status = getattr(getattr(error, "response", None), "status_code", None) if status == 401: sys.exit(f"API key rejected (401). Copy a current key from {DASHBOARD}") if status == 403: sys.exit("Streaming is not active for this key (403). Start a trial or renew your plan.") reason = "all connections are in use" if status == 429 else f"{type(error).__name__}: {error}" if opened_at is not None and time.monotonic() - opened_at >= 30: attempt = 0 # a healthy session resets backoff delay = min(30, 2**attempt) + random.random() / 4 attempt = min(attempt + 1, 5) log("closed", f"{reason}; reconnecting in {delay:.1f} s") await asyncio.sleep(delay) if __name__ == "__main__": if ACCOUNTS: add_accounts() try: asyncio.run(main()) except KeyboardInterrupt: print_summary() ``` 2. Save it as `tweetstream_example.py` 3. Run it with your key ```bash python3 -m venv tweetstream-venv && \ tweetstream-venv/bin/pip install 'websockets>=14' && \ TWEETSTREAM_API_KEY=YOUR_API_KEY tweetstream-venv/bin/python tweetstream_example.py ``` [Raw file: tweetstream_example.py](https://tweetstream.io/docs/examples/tweetstream_example.py) #### Expected output ```text connected wss://ws-global.tweetstream.io/ws auth ok, waiting for events post @marketdesk 2104934217937850514 183 ms "SOL breaks out of the 4h range. Watching $98.5 as…" update @marketdesk 2104934217937850514 chain: quote @projectteam 2104932246614966349 "Mainnet is live." -> reply @devteam 2104929205744566281 "Ship date?" update @marketdesk 2104934217937850514 full text "SOL breaks out of the 4h range. Watching $98.5 as support. Chart below." meta @marketdesk 2104934217937850514 tokens SOL $98.5 | ocr "SOL/USD 4h" post @devteam 2104934259042025479 223 ms "Ship date is set. Details here:" chain: reply @marketdesk 2104934217937850514 "SOL breaks out of the 4h range. Watchin…" quoted: quote @projectteam update @devteam 2104934259042025479 quoted: quote @projectteam 2104932246614966349 "Mainnet is live." delete @marketdesk 2104934217937850514 follow @marketdesk followed @projectteam summary latency p50 183 ms p95 223 ms (n=2) | events control/auth_pong 1, tweet/content 2, tweet/update 3, tweet/meta 1, tweet/delete 1, account/follow 1 ``` ### The event sequence These frames produce the expected output above. Their timestamps are illustrative. Each post starts with `tweet/content`. A `tweet/update` for the same `(platform, tweetId)` adds fields to it, and its `ref` links the post to the posts it quotes or replies to. 1. You send `auth_ping`. Sent as soon as the socket opens, to check the key. ```json { "op": "auth_ping" } ``` 2. Server sends `control/auth_pong`. The key works. The program prints an `auth` line and waits for events. ```json { "v": 1, "t": "control", "op": "auth_pong", "ts": 1790690396000, "d": {} } ``` 3. Server sends `tweet/content`. A new post, here with shortened text. The program stores it under `(platform, tweetId)` and prints it with its latency. ```json { "v": 1, "t": "tweet", "op": "content", "id": "2104934217937850514", "ts": 1790690400160, "d": { "tweetId": "2104934217937850514", "text": "SOL breaks out of the 4h range. Watching $98.5 as…", "createdAt": 1790690400000, "receivedAt": 1790690400150, "kind": "quote", "author": { "id": "1450012345678901248", "handle": "@marketdesk", "name": "Market Desk", "platform": "twitter" } } } ``` 4. Server sends `tweet/update`. Adds a reference to the same post. The program merges the fields over the stored post, replaces its `ref`, and prints the chain by following `ref.subtweet`. ```json { "v": 1, "t": "tweet", "op": "update", "id": "2104934217937850514", "ts": 1790690402000, "d": { "tweetId": "2104934217937850514", "platform": "twitter", "receivedAt": 1790690401990, "kind": "quote", "ref": { "type": "quote", "tweetId": "2104932246614966349", "text": "Mainnet is live.", "author": { "id": "1380123456789012480", "handle": "@projectteam", "name": "Project Team" }, "subtweet": { "type": "reply", "tweetId": "2104929205744566281", "text": "Ship date?", "author": { "id": "1290123456789012481", "handle": "@devteam", "name": "Dev Team" } } } } } ``` 5. Server sends `tweet/update`. Delivers the full text, with `textUpdateType` set to `completion`. The program merges it over the stored post and keeps the `ref` it already has. ```json { "v": 1, "t": "tweet", "op": "update", "id": "2104934217937850514", "ts": 1790690403000, "d": { "tweetId": "2104934217937850514", "platform": "twitter", "receivedAt": 1790690402990, "text": "SOL breaks out of the 4h range. Watching $98.5 as support. Chart below.", "textUpdateType": "completion" } } ``` 6. Server sends `tweet/meta`. Enrichment for the post. The program replaces the stored `meta` with this snapshot and prints tokens, markets, and OCR text. ```json { "v": 1, "t": "tweet", "op": "meta", "id": "2104934217937850514", "ts": 1790690404000, "d": { "tweetId": "2104934217937850514", "platform": "twitter", "receivedAt": 1790690403990, "detected": { "tokens": [ { "chain": "solana", "contract": "So11111111111111111111111111111111111111112", "name": "Wrapped SOL", "networkId": 1399811149, "priceUsd": 98.5, "sources": [ "text", "ocr" ], "symbol": "SOL" } ] }, "ocr": { "text": "SOL/USD 4h" } } } ``` 7. Server sends `tweet/content`. A reply that also quotes a post. `ref` is the post it replies to, and `quoted` is the post it quotes, which here names only its author for now. The program prints both. ```json { "v": 1, "t": "tweet", "op": "content", "id": "2104934259042025479", "ts": 1790690410000, "d": { "tweetId": "2104934259042025479", "text": "Ship date is set. Details here:", "createdAt": 1790690409800, "receivedAt": 1790690409990, "kind": "reply", "ref": { "type": "reply", "tweetId": "2104934217937850514", "text": "SOL breaks out of the 4h range. Watching $98.5 as support. Chart below.", "author": { "id": "1450012345678901248", "handle": "@marketdesk", "name": "Market Desk" } }, "quoted": { "type": "quote", "author": { "id": "1380123456789012480", "handle": "@projectteam" } }, "author": { "id": "1290123456789012481", "handle": "@devteam", "name": "Dev Team", "platform": "twitter" } } } ``` 8. Server sends `tweet/update`. Completes the quoted post. The program replaces the stored `quoted` and prints it. ```json { "v": 1, "t": "tweet", "op": "update", "id": "2104934259042025479", "ts": 1790690411000, "d": { "tweetId": "2104934259042025479", "platform": "twitter", "receivedAt": 1790690410990, "quoted": { "type": "quote", "tweetId": "2104932246614966349", "text": "Mainnet is live.", "author": { "id": "1380123456789012480", "handle": "@projectteam", "name": "Project Team" } } } } ``` 9. Server sends `tweet/delete`. The author deleted the post. The program marks it deleted and keeps its content. ```json { "v": 1, "t": "tweet", "op": "delete", "id": "2104934217937850514", "ts": 1790690430000, "d": { "eventId": "delete.264da58762fac7204da8", "tweetId": "2104934217937850514", "platform": "twitter", "author": { "id": "1450012345678901248", "handle": "@marketdesk" }, "deletedAt": 1790690429990, "receivedAt": 1790690429990 } } ``` 10. Server sends `account/follow`. A monitored account followed someone. The program prints one line and leaves stored posts alone. ```json { "v": 1, "t": "account", "op": "follow", "id": "follow-1450012345678901248-1380123456789012480", "ts": 1790690438000, "d": { "actor": { "id": "1450012345678901248", "handle": "@marketdesk" }, "target": { "id": "1380123456789012480", "handle": "@projectteam" }, "kind": "FOLLOW", "eventId": "follow-1450012345678901248-1380123456789012480", "observedAt": 1790690437990, "receivedAt": 1790690437990 } } ``` ### Connect and reconnect `connect()` opens the socket with two subprotocols, `tweetstream.v1` and `tweetstream.auth.token.`, then sends `auth_ping`. The `control/auth_pong` reply confirms the key. After a disconnect the program waits 1, 2, 4, 8, 16, and then 30 seconds between attempts, plus a little jitter. A session that stays up for 30 seconds resets the delay. A `401` or `403` stops the program with a message, because retrying will not fix the key or the plan. Node.js does not expose the HTTP status of a refused connection, so the TypeScript program asks `GET /api/me` for the reason. The Python program reads the status from the `websockets` error. ### Add accounts When `TWEETSTREAM_ACCOUNTS` has handles, `addAccounts()` sends them to `POST https://api.tweetstream.io/api/add-account` before connecting. A `207` response means some handles were added and some were not, so the program prints one line per handle with its `state`. Added accounts stay on your watchlist after the program exits. ### Posts and update chains The program stores each post by `(platform, tweetId)`. `tweet/content` creates the post, and `tweet/update` merges in only the fields it carries, so the text and author you already have stay in place. When an update includes `ref`, the program replaces the stored reference and prints the chain by following `ref.subtweet` from one referenced post to the next. An update can arrive before its content; the merge keeps the update's fields. `tweet/delete`, `tweet/pin`, and `tweet/unpin` change the stored post's state and leave its content alone. #### Merge updates and print the chain (TypeScript) ```typescript // Updates carry only the fields that changed, so merge them over what you stored. const merge = (base: Partial | null, patch: Partial | null) => ({ ...base, ...patch, author: { ...base?.author, ...patch?.author }, }); function referenceChain(ref: Reference | undefined): string { const links: string[] = []; // A referenced post can reference another one through ref.subtweet. for (let r = ref, depth = 0; r && depth < 8; r = r.subtweet, depth++) { // A reference can name only its author until an update adds its ID and text. const parts = [r.type ?? "ref", at(r.author), r.tweetId, r.text ? clip(r.text, 40) : undefined]; links.push(parts.filter(Boolean).join(" ")); } return links.join(" -> "); } "tweet/update": (d) => { const post = postFor(d); post.content = merge(post.content, d); // a ref or quoted in the update replaces the stored one const who = `${at(post.content.author)} ${d.tweetId}`; const changed = Object.keys(d).filter((k) => !["platform", "receivedAt", "tweetId"].includes(k)); if (d.ref) log("update", `${who} chain: ${referenceChain(d.ref)}`); if (d.quoted) log("update", `${who} quoted: ${referenceChain(d.quoted)}`); if (d.ref || d.quoted) return; if (d.textUpdateType === "completion") log("update", `${who} full text ${clip(d.text)}`); else log("update", `${who} changed ${changed.join(", ")}`); }, ``` #### Merge updates and print the chain (Python) ```python def merge(base, patch): # Updates carry only the fields that changed, so merge them over what you stored. base, patch = base or {}, patch or {} return {**base, **patch, "author": {**(base.get("author") or {}), **(patch.get("author") or {})}} def reference_chain(ref): links = [] # A referenced post can reference another one through subtweet. while ref and len(links) < 8: # A reference can name only its author until an update adds its ID and text. text = clip(ref["text"], 40) if ref.get("text") else None parts = [ref.get("type", "ref"), at(ref.get("author")), ref.get("tweetId"), text] links.append(" ".join(part for part in parts if part)) ref = ref.get("subtweet") return " -> ".join(links) def on_update(d, _): post = post_for(d) post["content"] = merge(post["content"], d) # a ref or quoted in the update replaces the stored one who = f"{at(post['content'].get('author'))} {d['tweetId']}" changed = ", ".join(k for k in d if k not in ("platform", "receivedAt", "tweetId")) if d.get("ref"): log("update", f"{who} chain: {reference_chain(d['ref'])}") if d.get("quoted"): log("update", f"{who} quoted: {reference_chain(d['quoted'])}") if d.get("ref") or d.get("quoted"): return if d.get("textUpdateType") == "completion": log("update", f"{who} full text {clip(d.get('text'))}") else: log("update", f"{who} changed {changed}") ``` ### Enrichment `tweet/meta` can arrive after the post. Each one is a complete snapshot, so the program replaces the stored metadata instead of merging it. The `meta` line lists detected tokens with prices, prediction markets with prices, and OCR text read from images, when present. ### Other events Follows, unfollows, profile changes, affiliate changes, callouts, FOMO theses and token verifications, news articles, and charity notices each print one line. Callouts, news, charity, and FOMO events arrive only after you turn them on in the dashboard. An unknown `t` and `op` pair is counted and skipped, and the connection stays open. If a handler fails, the program prints an `error` line and keeps reading. ### Measure latency The message handler reads the clock before it parses anything. For X posts, the publish time comes from the post ID: shift the ID right by 22 bits and add the Twitter epoch, `1288834974657`. Other platforms use `createdAt`. The difference is the time from publication to receipt on your machine, including the network path to you. A replayed post does not add a second sample. Every 60 seconds and when you press Ctrl+C, the program prints p50 and p95 over the most recent 10,000 posts, plus a count for each event type. #### Read the publish time (TypeScript) ```typescript function publishedAtMs(platform: string, d: PostContent): number | null { // X post IDs encode their publish time: (id >> 22) + the Twitter epoch. if (platform === "twitter" && /^\d+$/.test(d.tweetId)) { return Number((BigInt(d.tweetId) >> 22n) + TWITTER_EPOCH_MS); } return typeof d.createdAt === "number" ? d.createdAt : null; } ``` #### Read the publish time (Python) ```python def published_at_ms(platform, d): tweet_id = str(d.get("tweetId", "")) if platform == "twitter" and tweet_id.isdigit(): return (int(tweet_id) >> 22) + TWITTER_EPOCH_MS # X post IDs encode their publish time created_at = d.get("createdAt") return created_at if isinstance(created_at, (int, float)) else None ``` ### Optional settings Set these environment variables next to `TWEETSTREAM_API_KEY` in the run command. | Variable | Default | Use | | --- | --- | --- | | `TWEETSTREAM_API_KEY` | Required | Your API key. The program never prints it. | | `TWEETSTREAM_ACCOUNTS` | None | Comma-separated handles to add before connecting, such as `marketdesk,projectteam` | | `TWEETSTREAM_WS_URL` | `wss://ws-global.tweetstream.io/ws` | Use `wss://ws-iad.tweetstream.io/ws` when you run in the USA | ### Common mistakes - Treating `tweet/update` as a new post. It belongs to the post you stored under the same `(platform, tweetId)`. - Replacing the stored post with an update. An update carries only the fields it changes, so merge it. - Dropping an update that arrives before its content. Keep it, and when the content arrives, merge it in without overwriting the update's fields. - Merging a `tweet/meta` into older metadata. Each one is a full snapshot, so replace the stored one. - Ordering or deduplicating posts by the envelope `ts` or `id`. Use `(platform, tweetId)` for identity. - Closing the socket on an unknown `t` and `op` pair. Skip the frame and keep reading. - Retrying a `401` or `403` in a loop. A new connection will not fix the key or the plan. ### Troubleshooting - You only see `auth` and `summary` lines. Posts arrive when a monitored account posts. Add an active account, or check your watchlist with `GET /api/me`. After two quiet minutes the program prints a hint. - The program stops with `API key rejected (401)`. Copy the key again from the dashboard. A rotated key stops working. - The program stops with `Streaming is not active for this key (403)`. Start a trial or renew your plan, then run it again. - The program says all connections are in use. Your plan limits open WebSocket connections. Stop another client, or wait for an old connection to close. - Latency is negative or much higher than expected. The number compares your clock with the post's publish time, so sync your clock with NTP. Measure from the machine that runs your trading system. - Node.js reports `Unknown file extension ".ts"`. Your Node.js is older than 22.18. Update Node.js and run the command again. - Python reports `No module named 'websockets'`. Start the program with `tweetstream-venv/bin/python` as the run command shows. That environment has `websockets` installed. - Creating the virtual environment fails with `ensurepip is not available`. On Debian or Ubuntu, install the venv module with `sudo apt install python3-venv`, then run the Python command again. - pip reports `No matching distribution found for websockets>=14`. Your `python3` is older than 3.10. Install Python 3.10 or later and create the virtual environment with it. ### Build on it When you turn this program into a long-running consumer, start with the typed router and the reference consumer. - [Route every operation](https://tweetstream.io/docs/production-consumer#complete-router): Typed handlers for all 19 server operations. - [Build the reference consumer](https://tweetstream.io/docs/production-consumer#reference-consumer): Reconnects, durable recovery, and account management, one page each. - [Open-source Solana sniper bot](https://github.com/tweetstream-io/solana-sniper-bot): A TypeScript and Rust bot built on this feed that buys on posts, bio changes, follows, and callouts. ## Instagram WebSocket Connect to `wss://insta-ws.tweetstream.io/ws` with your TweetStream API key to receive new posts, reels, carousels, and stories from the Instagram accounts on your watchlist. Canonical URL: https://tweetstream.io/docs/instagram-websocket ### Quick start You need an active Instagram Tracking subscription or trial, at least one Instagram account on your dashboard watchlist, and your TweetStream API key. Run the example below. `Instagram feed connected` confirms authentication, and events print when a watched account publishes. | Setting | Value | Notes | | --- | --- | --- | | Endpoint | `wss://insta-ws.tweetstream.io/ws` | Separate from the X feed endpoints | | Subprotocol | `tweetstream.instagram.v1` | Required when you send any subprotocol, the auth token included. Other subprotocols get HTTP 400 | | Auth protocol | `tweetstream.auth.token.` | Your existing TweetStream API key | #### Run the TypeScript smoke test ```typescript // bun add ws // TWEETSTREAM_API_KEY=ts_... bun run instagram.ts import WebSocket from "ws"; const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) { throw new Error("Missing TWEETSTREAM_API_KEY"); } const ws = new WebSocket("wss://insta-ws.tweetstream.io/ws", [ "tweetstream.instagram.v1", `tweetstream.auth.token.${apiKey}`, ]); ws.on("open", () => { console.log("Instagram feed connected"); }); ws.on("message", (raw) => { const event = JSON.parse(raw.toString()); if (event.t === "instagram" && (event.op === "content" || event.op === "update")) { console.log(event.op, event.d.kind, event.d.author.username, event.d.url); } }); ws.on("unexpected-response", (_request, response) => { console.error("Connection rejected", response.statusCode, response.statusMessage); response.resume(); process.exitCode = 1; }); ws.on("close", (code, reason) => { console.log("Instagram feed closed", code, reason.toString()); }); ``` ### Authenticate The Instagram WebSocket accepts the same API key and the same credential forms as the X feed. If you send the key as `tweetstream.auth.token.`, also offer `tweetstream.instagram.v1`. Keep the key on your server and out of public browser code. | Context | Header or protocol | Notes | | --- | --- | --- | | WebSocket | `tweetstream.instagram.v1` + `tweetstream.auth.token.` | Preferred | | WebSocket fallback | `Authorization: Bearer ` or `?apiKey=` | Use the query form only when your runtime cannot set headers | ### Read the envelope Every frame is one JSON envelope shaped like the X feed. Route by `t`, then `op`, and ignore operations you do not recognize without closing the socket. | Field | Type | Meaning | | --- | --- | --- | | `v` | `1` | Envelope version | | `t` | `instagram` or `control` | Channel | | `op` | `content`, `update`, or `auth_pong` | Operation | | `id` | string | The media ID. An update event reuses the ID of the content event it replaces | | `ts` | number | When TweetStream sent the frame, in Unix milliseconds | | `d` | object | Payload for the operation | #### Instagram envelope types ```typescript type InstagramKind = 'post' | 'reel' | 'carousel' | 'story' | 'unknown'; type InstagramMedia = { // Position in the media array, starting at 0. index: number; type: 'image' | 'video' | 'unknown'; url: string; // Present only on an image that is a video's cover. cover?: true; }; type InstagramContent = { // Instagram media ID; also the envelope id. id: string; // Present when known; the post URL uses it. shortcode?: string; kind: InstagramKind; url: string; author: { id?: string; // Lowercase, without a leading @. username: string; }; // Empty string when the post has no caption. caption: string; // May be empty or partial; see the media notes. media: Array; // Publish time in Unix milliseconds, or null when it is not known. createdAt: number | null; // True when createdAt is an estimate. createdAtEstimated: boolean; // When TweetStream received the post, in Unix milliseconds. receivedAt: number; // Content events only. True when this post reached TweetStream well after its // publish time; the post is still new to you. A missing flag does not mean // the post is recent: when createdAt is set, compare it with receivedAt. late?: true; }; type InstagramContentEnvelope = { v: 1; t: 'instagram'; op: 'content'; id: string; ts: number; d: InstagramContent; }; type InstagramUpdateEnvelope = { v: 1; t: 'instagram'; // Insert, or replace the stored event with the same id. Sent at most once per id. op: 'update'; id: string; ts: number; // Never carries late: keep the value from the content event, or compare // createdAt with receivedAt if you never got one. d: Omit; }; type InstagramAuthPongEnvelope = { v: 1; t: 'control'; op: 'auth_pong'; ts: number; d: Record; }; type InstagramEnvelope = | InstagramContentEnvelope | InstagramUpdateEnvelope | InstagramAuthPongEnvelope; ``` ### Content kinds `d.kind` says what was published when it is known. `d.url` links to the content on Instagram, or to the author's profile when no shortcode is known. | Kind | Meaning | URL shape | | --- | --- | --- | | `post` | A feed post with one image or video | `instagram.com/p//` | | `reel` | A reel | `instagram.com/reel//` | | `carousel` | A feed post with several images or videos | `instagram.com/p//` | | `story` | A story | `instagram.com/stories///` | | `unknown` | The kind was not established. The event still carries the ID, author, URL, and any media found, so treat it as new content from that account | `instagram.com/p//`, or the author's profile when no shortcode is known | ### Media order and covers - `index` is the item's position in `media`, starting at 0. `media` follows the post's slide order when that order is known. In a carousel that mixes photos and videos, the photos may come first. - `cover: true` marks an image that is a video's cover. Other items omit the field. - `type` is `image`, `video`, or `unknown` when the type was not established. - `media` can be empty or list fewer items than the post has. A later `update` may bring the rest. Open `url` for the full post. - Media URLs can expire. Download the files you need soon after the event arrives. ### Timestamps | Field | Type | Meaning | | --- | --- | --- | | `createdAt` | number or `null` | Publish time in Unix milliseconds. `null` when it is not known | | `createdAtEstimated` | boolean | `true` when `createdAt` is an estimate | | `receivedAt` | number | When TweetStream received the content, in Unix milliseconds | | `late` | `true`, or absent | `true` when this post reached TweetStream well after its publish time. The post is still new to you. Only `content` events carry it, never `update`. A missing `late` does not mean the post is recent: when `createdAt` is set, compare it with `receivedAt` | ### Example events Each example is a complete frame as it arrives on the socket. #### Carousel ```json { "v": 1, "t": "instagram", "op": "content", "id": "3988012345678901234", "ts": 1772000001060, "d": { "id": "3988012345678901234", "shortcode": "DdsPyK1GrTK", "kind": "carousel", "url": "https://www.instagram.com/p/DdsPyK1GrTK/", "author": { "id": "25025320", "username": "examplebrand" }, "caption": "Three frames from launch day", "media": [ { "index": 0, "type": "image", "url": "https://scontent-iad3-1.cdninstagram.com/v/1.jpg" }, { "index": 1, "type": "video", "url": "https://scontent-iad3-1.cdninstagram.com/v/2.mp4" }, { "index": 2, "type": "image", "url": "https://scontent-iad3-1.cdninstagram.com/v/2.jpg", "cover": true } ], "createdAt": 1772000000000, "createdAtEstimated": false, "receivedAt": 1772000001050 } } ``` #### Reel ```json { "v": 1, "t": "instagram", "op": "content", "id": "3987848477383929083", "ts": 1772000001060, "d": { "id": "3987848477383929083", "shortcode": "DdXrw_IjSz7", "kind": "reel", "url": "https://www.instagram.com/reel/DdXrw_IjSz7/", "author": { "id": "25025320", "username": "examplebrand" }, "caption": "New drop", "media": [ { "index": 0, "type": "video", "url": "https://scontent-iad3-1.cdninstagram.com/v/reel.mp4" } ], "createdAt": 1772000000000, "createdAtEstimated": false, "receivedAt": 1772000001050 } } ``` #### Story with an estimated publish time ```json { "v": 1, "t": "instagram", "op": "content", "id": "3988000000000000001", "ts": 1772000001060, "d": { "id": "3988000000000000001", "kind": "story", "url": "https://www.instagram.com/stories/examplebrand/3988000000000000001/", "author": { "id": "25025320", "username": "examplebrand" }, "caption": "", "media": [ { "index": 0, "type": "image", "url": "https://scontent-iad3-1.cdninstagram.com/v/story.jpg" } ], "createdAt": 1772000000000, "createdAtEstimated": true, "receivedAt": 1772000001050 } } ``` #### Kind not established ```json { "v": 1, "t": "instagram", "op": "content", "id": "3987848477383929083", "ts": 1772000001060, "d": { "id": "3987848477383929083", "shortcode": "DdXrw_IjSz7", "kind": "unknown", "url": "https://www.instagram.com/p/DdXrw_IjSz7/", "author": { "id": "25025320", "username": "examplebrand" }, "caption": "Kind not established", "media": [ { "index": 0, "type": "unknown", "url": "https://scontent-iad3-1.cdninstagram.com/v/first.jpg" } ], "createdAt": null, "createdAtEstimated": false, "receivedAt": 1772000001050 } } ``` #### Late post ```json { "v": 1, "t": "instagram", "op": "content", "id": "3987848477383929083", "ts": 1772000001060, "d": { "id": "3987848477383929083", "shortcode": "DdXrw_IjSz7", "kind": "post", "url": "https://www.instagram.com/p/DdXrw_IjSz7/", "author": { "id": "25025320", "username": "examplebrand" }, "caption": "Behind the scenes", "createdAt": 1771999101050, "media": [ { "type": "image", "url": "https://scontent-iad3-1.cdninstagram.com/v/late.jpg", "index": 0 } ], "createdAtEstimated": false, "late": true, "receivedAt": 1772000001050 } } ``` ### Updates An `update` event carries a complete `d` payload for its `id`. If you already stored an event with that `id`, replace it with the new one instead of merging fields. If you have not seen that `id`, for example because you connected after the first event, treat the update as new content. TweetStream sends at most one update per event, and only when it has a more complete version, for example one that adds media or a known kind. Updates arrive on the WebSocket only. Discord posts are not edited. #### Carousel update ```json { "v": 1, "t": "instagram", "op": "update", "id": "3988012345678901234", "ts": 1772000001060, "d": { "id": "3988012345678901234", "shortcode": "DdsPyK1GrTK", "kind": "carousel", "url": "https://www.instagram.com/p/DdsPyK1GrTK/", "author": { "id": "25025320", "username": "examplebrand" }, "caption": "Three frames from launch day", "createdAt": 1772000000000, "media": [ { "type": "image", "url": "https://scontent-iad3-1.cdninstagram.com/v/1.jpg", "index": 0 }, { "type": "video", "url": "https://scontent-iad3-1.cdninstagram.com/v/2.mp4", "index": 1 }, { "type": "image", "url": "https://scontent-iad3-1.cdninstagram.com/v/2.jpg", "index": 2, "cover": true } ], "createdAtEstimated": false, "receivedAt": 1772000001050 } } ``` ### Check authentication Send `{ "op": "auth_ping" }` when your application needs an authentication check. A valid connection answers with `control/auth_pong` and an empty data object. #### Authentication ping [Use the first complete copy of this example.](https://tweetstream.io/docs/control#auth-ping-message) #### Authentication pong [Use the first complete copy of this example.](https://tweetstream.io/docs/control#auth-pong-event) ### Manage accounts over HTTP Use your API key to change the same watchlist the dashboard shows. Send `accounts` as one username or an array of up to 100, with or without `@`. A `207` means some accounts changed and others were rejected; `rejected` gives the reason for each one. Adding an account that is already on the list returns `duplicate`, and removing one that is not on it returns `not_tracked`. Neither counts as a failure, so retrying a request is safe. | Method | Path | Result | | --- | --- | --- | | `GET` | `/api/instagram/accounts` | Your accounts, each `live`, `pending`, or `paused`, and your `limit` | | `POST` | `/api/instagram/add-account` | Adds accounts. Over your limit they come back as `capacity` | | `DELETE` | `/api/instagram/remove-account` | Removes accounts and lists them in `removed` | #### Add Instagram accounts ```typescript const apiKey = process.env.TWEETSTREAM_API_KEY; if (!apiKey) throw new Error("Missing TWEETSTREAM_API_KEY"); const response = await fetch("https://api.tweetstream.io/api/instagram/add-account", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ accounts: ["nasa", "@natgeo"], }), }); if (!response.ok && response.status !== 207) { const detail = await response.text(); throw new Error(`Add failed (${response.status}): ${detail}`); } const { accounts, limit, rejected } = await response.json(); console.log(`${accounts.length}/${limit} accounts`, rejected); ``` ### Connections and accounts - Each Instagram Tracking subscription includes 3 Instagram WebSocket connections, or 1 during the trial. They are separate from your X plan's connections. - Add or remove Instagram accounts at any time, in the dashboard or over HTTP. Account changes never change your bill. - Events can also go to a Discord channel. Set that up in the dashboard. ## Full API reference ## Replay stored events Returns stored events newest first. Repeat handle parameters or use comma-separated values. Canonical URL: https://tweetstream.io/docs/api/get-history ### `GET /api/history` `https://api.tweetstream.io/api/history` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Query parameters | Name | Type | Description | | --- | --- | --- | | `handle` | `string` | Tracked handle. Repeat or provide a comma-separated list. | | `handles` | `string` | Alias for handle. Repeat or provide a comma-separated list. | | `handle[]` | `string[]` | Array-style alias for handle. | | `handles[]` | `string[]` | Array-style alias for handles. | | `cursor` | `string` | Stable cursor returned by a previous history page. | | `startDate` | `string` | | | `endDate` | `string` | | | `limit` | `integer` | | | `type` | `enum` | | ### Response fields | Name | Type | Description | | --- | --- | --- | | `data` | `object[]`, required | | | `data.body` | `string`, required | | | `data.content` | `object`, required | | | `data.link` | `string`, required | | | `data.messageType` | `enum`, required | | | `data.meta` | `object` | | | `data.receivedTime` | `string`, required | | | `data.time` | `string`, required | | | `data.tweetId` | `string`, required | | | `data.twitterHandle` | `string \| null`, required | | | `data.twitterId` | `string`, required | | | `metadata` | `object`, required | | | `metadata.count` | `integer`, required | | | `metadata.endDate` | `string` | | | `metadata.handle` | `string` | | | `metadata.handles` | `string[]` | | | `metadata.nextCursor` | `string \| null`, required | | | `metadata.startDate` | `string` | | | `metadata.type` | `enum` | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `429` | Rate limit reached | | | `500` | The request could not be completed | | #### 200 ```json { "data": [ { "tweetId": "account:affiliate:aff_01JQ8YQ5K8B8QKH6M0P8A1V2WX", "twitterId": "123", "twitterHandle": "organization", "body": "Added New Member (@newmember) to affiliate list", "time": "2025-04-09T00:00:00.123Z", "receivedTime": "2025-04-09T00:00:00.123Z", "link": "https://x.com/newmember", "messageType": "AFFILIATE", "content": { "action": "added", "eventId": "aff_01JQ8YQ5K8B8QKH6M0P8A1V2WX", "observedAt": 1744156800123, "receivedAt": 1744156800123, "organization": { "id": "123", "handle": "@organization", "name": "Organization", "verifiedType": "business" }, "member": { "id": "456", "handle": "@newmember", "name": "New Member", "profileImage": "https://pbs.twimg.com/profile_images/newmember_normal.jpg" } } } ], "metadata": { "count": 1, "nextCursor": null, "type": "AFFILIATE" } } ``` #### 400 ```json { "error": "" } ``` #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 429 ```json { "error": "", "retryAfterSeconds": 0 } ``` #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://api.tweetstream.io/api/history \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/history", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://api.tweetstream.io/api/history", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, ) print(response.status_code, response.json()) ``` ## Search posts Returns recent X posts that match an X search query, in X's Latest order (not strictly by ID), and the URL of the next page. One search returns at most 100 posts across all its pages; after the 100th post, next is null. Canonical URL: https://tweetstream.io/docs/api/search-posts ### `GET /api/search/posts` `https://api.tweetstream.io/api/search/posts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Query parameters | Name | Type | Description | | --- | --- | --- | | `query` | `string`, required | X search query, operators included. | | `limit` | `integer` | Most posts to return. | | `page` | `string` | Opaque; only ever taken from next. | ### Response fields | Name | Type | Description | | --- | --- | --- | | `next` | `string \| null`, required | Absolute URL of the next page: request it as it is, with the same API key. Null when there is nothing more or the search has returned 100 posts. Works for 30 minutes. | | `posts` | `object[]`, required | | | `posts.kind` | `enum` | | | `posts.quoted` | `object` | The post a reply also quotes. A quote keeps the post it quotes in ref and has no quoted. | | `posts.quoted.type` | `string`, required | | | `posts.ref` | `object` | | | `posts.ref.type` | `enum`, required | | | `posts.metrics` | `object`, required | | | `posts.metrics.bookmarks` | `integer`, required | | | `posts.metrics.likes` | `integer`, required | | | `posts.metrics.quotes` | `integer`, required | | | `posts.metrics.replies` | `integer`, required | | | `posts.metrics.reposts` | `integer`, required | | | `posts.metrics.views` | `integer \| null`, required | | | `posts.tweetId` | `string`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid query or limit, or a page link that was changed or is over 30 minutes old. Search again without page. | | | `401` | Missing or invalid API key | | | `403` | The API key's account has no current Pro, Ultra Speed, Scale subscription. | | | `405` | Only GET is supported | | | `429` | The account's search allowance is spent or its searches in progress are at the plan's limit: Pro 60 per minute (bursts of 10, 4 in progress); Ultra Speed 120 per minute (bursts of 10, 6 in progress); Scale 300 per minute (bursts of 10, 10 in progress) | `Retry-After` | | `503` | Post search or authentication is temporarily unavailable | `Retry-After` | #### 200 ```json { "posts": [ { "tweetId": "2118183412095201280", "text": "Solana validators shipped the new client today.", "createdAt": 1793849254045, "kind": "post", "link": "https://x.com/marketdesk/status/2118183412095201280", "author": { "id": "1189745302", "handle": "@marketdesk", "name": "Market Desk", "platform": "twitter", "verifiedType": "blue", "followersCount": 48210, "followingCount": 312, "profileImage": "https://pbs.twimg.com/profile_images/marketdesk_400x400.jpg" }, "metrics": { "likes": 1204, "replies": 87, "reposts": 230, "quotes": 19, "bookmarks": 41, "views": null } } ], "next": "https://api.tweetstream.io/api/search/posts?limit=1&page=AZx3q0Vh1mR2k9Q&query=solana+lang%3Aen+-is%3Aretweet" } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request GET \ --url 'https://api.tweetstream.io/api/search/posts?query=solana+lang%3Aen+-is%3Aretweet' \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/search/posts?query=solana+lang%3Aen+-is%3Aretweet", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://api.tweetstream.io/api/search/posts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, params=[("query", "solana lang:en -is:retweet")], ) print(response.status_code, response.json()) ``` ## Look up a post Returns one post and its engagement counts. Canonical URL: https://tweetstream.io/docs/api/lookup-tweet ### `GET /api/tweet/{id}` `https://api.tweetstream.io/api/tweet/{id}` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Path parameters | Name | Type | Description | | --- | --- | --- | | `id` | `string`, required | Post ID. | ### Response fields | Name | Type | Description | | --- | --- | --- | | `metrics` | `object`, required | | | `metrics.bookmarks` | `integer`, required | | | `metrics.likes` | `integer`, required | | | `metrics.quotes` | `integer`, required | | | `metrics.replies` | `integer`, required | | | `metrics.reposts` | `integer`, required | | | `metrics.views` | `integer \| null`, required | | | `tweet` | `object`, required | The same fields as content in a TWEET History row. A reply that also quotes a post has kind reply, its parent in ref, and the post it quotes in quoted. | | `tweet.kind` | `enum` | | | `tweet.quoted` | `object` | The post a reply also quotes. A quote keeps the post it quotes in ref and has no quoted. | | `tweet.quoted.type` | `string`, required | | | `tweet.ref` | `object` | | | `tweet.ref.type` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid post ID | | | `401` | Missing or invalid API key | | | `403` | The API key's account has no paid or trialing subscription. | | | `404` | Post not found | | | `429` | Rate limit reached (60 lookups per minute per account, in bursts of up to 10) or 4 lookups already in progress for the account | `Retry-After` | | `503` | Lookup or authentication is temporarily unavailable | `Retry-After` | #### 200 ```json { "tweet": { "tweetId": "1234567890", "text": "Rate decision at 2pm ET.", "createdAt": 1744156800000, "kind": "post", "link": "https://x.com/marketdesk/status/1234567890", "author": { "id": "1189745302", "handle": "@marketdesk", "name": "Market Desk", "platform": "twitter", "verifiedType": "blue", "followersCount": 48210, "followingCount": 312, "joinedAt": 1358208000000, "profileImage": "https://pbs.twimg.com/profile_images/marketdesk_400x400.jpg" } }, "metrics": { "likes": 1204, "replies": 87, "reposts": 230, "quotes": 19, "bookmarks": 41, "views": 98213 } } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://api.tweetstream.io/api/tweet/1585841080431321088 \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/tweet/1585841080431321088", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://api.tweetstream.io/api/tweet/1585841080431321088", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, ) print(response.status_code, response.json()) ``` ## Look up an account Returns one account's profile. Canonical URL: https://tweetstream.io/docs/api/lookup-user ### `GET /api/user/{id}` `https://api.tweetstream.io/api/user/{id}` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Path parameters | Name | Type | Description | | --- | --- | --- | | `id` | `string`, required | Numeric account ID, or a handle with or without @. A handle made only of digits needs the @. | ### Response fields | Name | Type | Description | | --- | --- | --- | | `pinnedTweet` | `object \| null`, required | The account's pinned post, with the same fields as tweet in a post lookup. Filled in only for accounts TweetStream has seen pin a post. Null otherwise, after the account unpins, or when the post can't be shown right now. | | `user` | `object`, required | The same fields as author in WebSocket post events. | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid account ID or handle | | | `401` | Missing or invalid API key | | | `403` | The API key's account has no paid or trialing subscription. | | | `404` | Account not found | | | `429` | Rate limit reached (60 lookups per minute per account, in bursts of up to 10) or 4 lookups already in progress for the account | `Retry-After` | | `503` | Lookup or authentication is temporarily unavailable | `Retry-After` | #### 200 ```json { "user": { "id": "1189745302", "handle": "@marketdesk", "name": "Market Desk", "platform": "twitter", "verifiedType": "blue", "followersCount": 48210, "followingCount": 312, "joinedAt": 1358208000000, "profileImage": "https://pbs.twimg.com/profile_images/marketdesk_400x400.jpg" }, "pinnedTweet": { "tweetId": "1234567890", "text": "Rate decision at 2pm ET.", "createdAt": 1744156800000, "kind": "post", "link": "https://x.com/marketdesk/status/1234567890", "author": { "id": "1189745302", "handle": "@marketdesk", "name": "Market Desk", "platform": "twitter", "verifiedType": "blue", "followersCount": 48210, "followingCount": 312, "joinedAt": 1358208000000, "profileImage": "https://pbs.twimg.com/profile_images/marketdesk_400x400.jpg" } } } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://api.tweetstream.io/api/user/@marketdesk \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/user/@marketdesk", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://api.tweetstream.io/api/user/@marketdesk", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, ) print(response.status_code, response.json()) ``` ## Change an account's Discord webhook and keyword filters Change the Discord webhook and keyword filters for one tracked account. Omitted fields keep their saved value. Canonical URL: https://tweetstream.io/docs/api/update-account-settings ### `PATCH /api/account-settings` `https://api.tweetstream.io/api/account-settings` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `account` | `string`, required | | | `discordWebhook` | `string \| null` | A `https://discord.com/api/webhooks/...` or `https://discordapp.com/api/webhooks/...` URL, or `null` to use the global webhook. | | `keywords` | `string[]` | Skip this account's posts whose text contains any of these words. | #### Body example ```json { "account": "marketdesk", "keywords": [ "solana", "etf" ] } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `account` | `string`, required | | | `discordWebhook` | `string \| null`, required | | | `keywords` | `string[]`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `404` | The requested resource was not found | | | `500` | The request could not be completed | | #### 200 ```json { "account": "", "discordWebhook": "", "keywords": [ "" ] } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request PATCH \ --url https://api.tweetstream.io/api/account-settings \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "account": "marketdesk", "keywords": [ "solana", "etf" ] }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/account-settings", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "account": "marketdesk", "keywords": [ "solana", "etf" ] }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.patch( "https://api.tweetstream.io/api/account-settings", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "account": "marketdesk", "keywords": [ "solana", "etf", ], }, ) print(response.status_code, response.json()) ``` ## Add monitored accounts Add one or more monitored X/Twitter accounts. Canonical URL: https://tweetstream.io/docs/api/add-accounts ### `POST /api/add-account` `https://api.tweetstream.io/api/add-account` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `accounts` | `string \| string[]`, required | | #### Body example ```json { "accounts": [ "marketdesk", "realDonaldTrump" ] } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `action` | `enum`, required | | | `error` | `string \| null`, required | | | `requestId` | `string`, required | | | `results` | `object[]`, required | | | `results.input` | `string`, required | | | `results.message` | `string` | | | `results.state` | `enum`, required | | | `summary` | `object`, required | | | `summary.failed` | `integer`, required | | | `summary.succeeded` | `integer`, required | | | `summary.total` | `integer`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `207` | Some requested account operations succeeded and some failed | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `429` | Too many handle requests | `Retry-After` | | `500` | The request could not be completed | | | `503` | Account management is temporarily unavailable | | #### 200 ```json { "action": "follow", "error": "", "requestId": "", "results": [ { "input": "", "message": "", "state": "added" } ], "summary": { "failed": 0, "succeeded": 0, "total": 0 } } ``` #### 207 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/add-accounts#responses) #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/add-accounts#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/add-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://api.tweetstream.io/api/add-account \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "accounts": [ "marketdesk", "realDonaldTrump" ] }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/add-account", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "accounts": [ "marketdesk", "realDonaldTrump" ] }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://api.tweetstream.io/api/add-account", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "accounts": [ "marketdesk", "realDonaldTrump", ], }, ) print(response.status_code, response.json()) ``` ## Disable affiliate-list alerts for an account DELETE /api/affiliate-alerts stops affiliate-list change alerts for one monitored account and returns the account with affiliateAlertsEnabled false. Canonical URL: https://tweetstream.io/docs/api/disable-affiliate-alerts ### `DELETE /api/affiliate-alerts` `https://api.tweetstream.io/api/affiliate-alerts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `account` | `string`, required | | #### Body example ```json { "account": "marketdesk" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `account` | `string`, required | | | `affiliateAlertsEnabled` | `boolean`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `404` | The requested resource was not found | | | `500` | The request could not be completed | | #### 200 ```json { "account": "", "affiliateAlertsEnabled": true } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request DELETE \ --url https://api.tweetstream.io/api/affiliate-alerts \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "account": "marketdesk" }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/affiliate-alerts", { method: "DELETE", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "account": "marketdesk" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.delete( "https://api.tweetstream.io/api/affiliate-alerts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "account": "marketdesk", }, ) print(response.status_code, response.json()) ``` ## Enable affiliate-list alerts for an account POST /api/affiliate-alerts sends an alert whenever a monitored account's affiliate list gains or loses a member. It returns the account and its new setting. Canonical URL: https://tweetstream.io/docs/api/enable-affiliate-alerts ### `POST /api/affiliate-alerts` `https://api.tweetstream.io/api/affiliate-alerts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `account` | `string`, required | | #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/disable-affiliate-alerts#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `account` | `string`, required | | | `affiliateAlertsEnabled` | `boolean`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `404` | The requested resource was not found | | | `500` | The request could not be completed | | #### 200 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/disable-affiliate-alerts#responses) #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://api.tweetstream.io/api/affiliate-alerts \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "account": "marketdesk" }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/affiliate-alerts", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "account": "marketdesk" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://api.tweetstream.io/api/affiliate-alerts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "account": "marketdesk", }, ) print(response.status_code, response.json()) ``` ## Disable a Binance Square account DELETE /api/binance-square stops posts from one Binance Square account reaching your stream and returns the account with binanceSquareEnabled false. Canonical URL: https://tweetstream.io/docs/api/disable-binance-square-account ### `DELETE /api/binance-square` `https://api.tweetstream.io/api/binance-square` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `account` | `string`, required | | #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/disable-affiliate-alerts#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `account` | `string`, required | | | `binanceSquareEnabled` | `boolean`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `500` | The request could not be completed | | #### 200 ```json { "account": "", "binanceSquareEnabled": true } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request DELETE \ --url https://api.tweetstream.io/api/binance-square \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "account": "marketdesk" }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/binance-square", { method: "DELETE", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "account": "marketdesk" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.delete( "https://api.tweetstream.io/api/binance-square", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "account": "marketdesk", }, ) print(response.status_code, response.json()) ``` ## List available Binance Square accounts and settings GET /api/binance-square lists the Binance Square accounts you can stream, each with its display name, profile link and whether you have it enabled. Canonical URL: https://tweetstream.io/docs/api/list-binance-square-accounts ### `GET /api/binance-square` `https://api.tweetstream.io/api/binance-square` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Response fields | Name | Type | Description | | --- | --- | --- | | `accounts` | `object[]`, required | | | `accounts.avatarUrl` | `string \| null`, required | | | `accounts.displayName` | `string`, required | | | `accounts.enabled` | `boolean`, required | | | `accounts.profileUrl` | `string`, required | | | `accounts.squareHandle` | `string`, required | | | `canManage` | `boolean`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `500` | The request could not be completed | | #### 200 ```json { "accounts": [ { "avatarUrl": "", "displayName": "", "enabled": true, "profileUrl": "", "squareHandle": "" } ], "canManage": true } ``` #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://api.tweetstream.io/api/binance-square \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/binance-square", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://api.tweetstream.io/api/binance-square", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, ) print(response.status_code, response.json()) ``` ## Enable a Binance Square account POST /api/binance-square adds posts from one Binance Square account to your stream. Pick a handle from the list endpoint; the response confirms the change. Canonical URL: https://tweetstream.io/docs/api/enable-binance-square-account ### `POST /api/binance-square` `https://api.tweetstream.io/api/binance-square` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `account` | `string`, required | | #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/disable-affiliate-alerts#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `account` | `string`, required | | | `binanceSquareEnabled` | `boolean`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `500` | The request could not be completed | | #### 200 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/disable-binance-square-account#responses) #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://api.tweetstream.io/api/binance-square \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "account": "marketdesk" }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/binance-square", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "account": "marketdesk" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://api.tweetstream.io/api/binance-square", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "account": "marketdesk", }, ) print(response.status_code, response.json()) ``` ## List FOMO users, coins, and pump.fun accounts GET /api/callouts lists the FOMO users, FOMO coins and pump.fun callers you track, any pending additions, and each platform's capacity on your plan. Canonical URL: https://tweetstream.io/docs/api/list-fomo-and-callout-subscriptions ### `GET /api/callouts` `https://api.tweetstream.io/api/callouts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Response fields | Name | Type | Description | | --- | --- | --- | | `caller` | `object` | | | `caller.callerId` | `string`, required | | | `caller.createdAt` | `string`, required | | | `caller.label` | `string`, required | | | `caller.platform` | `enum`, required | | | `caller.username` | `string`, required | | | `caller.metadata` | `object` | | | `caller.metadata.displayName` | `string` | | | `caller.metadata.avatarUrl` | `string` | | | `caller.metadata.tokenAddress` | `string` | | | `caller.metadata.symbol` | `string` | | | `caller.metadata.name` | `string` | | | `caller.metadata.imageUrl` | `string` | | | `caller.metadata.networkId` | `integer` | | | `callers` | `object[] \| null`, required | | | `callers.callerId` | `string`, required | | | `callers.createdAt` | `string`, required | | | `callers.label` | `string`, required | | | `callers.platform` | `enum`, required | | | `callers.username` | `string`, required | | | `callers.metadata` | `object` | | | `callers.metadata.displayName` | `string` | | | `callers.metadata.avatarUrl` | `string` | | | `callers.metadata.tokenAddress` | `string` | | | `callers.metadata.symbol` | `string` | | | `callers.metadata.name` | `string` | | | `callers.metadata.imageUrl` | `string` | | | `callers.metadata.networkId` | `integer` | | | `pending` | `object[] \| null`, required | | | `pending.createdAt` | `string`, required | | | `pending.intentId` | `string`, required | | | `pending.input` | `string`, required | | | `pending.label` | `string`, required | | | `pending.platform` | `enum`, required | | | `limit` | `enum`, required | Current pump.fun capacity, the same as limits.pump_fun. Read limits for each platform's capacity. | | `limits` | `object`, required | Current platform capacity. All values are 0 when the account has no active eligible plan. | | `limits.pump_fun` | `enum`, required | | | `limits.fomo_user` | `integer`, required | | | `limits.fomo_coin` | `enum`, required | | | `removed` | `boolean` | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `500` | The request could not be completed | | | `503` | Temporarily unavailable | | #### 200 ```json { "caller": { "callerId": "", "createdAt": "2026-01-01T00:00:00Z", "label": "", "platform": "pump_fun", "username": "", "metadata": { "displayName": "", "avatarUrl": "", "tokenAddress": "", "symbol": "", "name": "", "imageUrl": "", "networkId": 123 } }, "callers": [ { "callerId": "", "createdAt": "2026-01-01T00:00:00Z", "label": "", "platform": "pump_fun", "username": "", "metadata": { "displayName": "", "avatarUrl": "", "tokenAddress": "", "symbol": "", "name": "", "imageUrl": "", "networkId": 123 } } ], "pending": [ { "createdAt": "2026-01-01T00:00:00Z", "intentId": "", "input": "", "label": "", "platform": "pump_fun" } ], "limit": 0, "limits": { "pump_fun": 0, "fomo_user": 0, "fomo_coin": 0 }, "removed": true } ``` #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://api.tweetstream.io/api/callouts \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/callouts", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://api.tweetstream.io/api/callouts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, ) print(response.status_code, response.json()) ``` ## Add a FOMO user, coin, or pump.fun account PUT /api/callouts tracks a FOMO user, FOMO coin or pump.fun caller, with an optional label. It returns the updated list; 409 means that platform is full. Canonical URL: https://tweetstream.io/docs/api/add-fomo-or-callout-subscription ### `PUT /api/callouts` `https://api.tweetstream.io/api/callouts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `platform` | `enum`, required | | | `input` | `string`, required | | | `label` | `string` | | #### Body example ```json { "input": "marketdesk", "label": "Market Desk", "platform": "pump_fun" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `caller` | `object` | | | `caller.callerId` | `string`, required | | | `caller.createdAt` | `string`, required | | | `caller.label` | `string`, required | | | `caller.platform` | `enum`, required | | | `caller.username` | `string`, required | | | `caller.metadata` | `object` | | | `caller.metadata.displayName` | `string` | | | `caller.metadata.avatarUrl` | `string` | | | `caller.metadata.tokenAddress` | `string` | | | `caller.metadata.symbol` | `string` | | | `caller.metadata.name` | `string` | | | `caller.metadata.imageUrl` | `string` | | | `caller.metadata.networkId` | `integer` | | | `callers` | `object[] \| null`, required | | | `callers.callerId` | `string`, required | | | `callers.createdAt` | `string`, required | | | `callers.label` | `string`, required | | | `callers.platform` | `enum`, required | | | `callers.username` | `string`, required | | | `callers.metadata` | `object` | | | `callers.metadata.displayName` | `string` | | | `callers.metadata.avatarUrl` | `string` | | | `callers.metadata.tokenAddress` | `string` | | | `callers.metadata.symbol` | `string` | | | `callers.metadata.name` | `string` | | | `callers.metadata.imageUrl` | `string` | | | `callers.metadata.networkId` | `integer` | | | `pending` | `object[] \| null`, required | | | `pending.createdAt` | `string`, required | | | `pending.intentId` | `string`, required | | | `pending.input` | `string`, required | | | `pending.label` | `string`, required | | | `pending.platform` | `enum`, required | | | `limit` | `enum`, required | Current pump.fun capacity, the same as limits.pump_fun. Read limits for each platform's capacity. | | `limits` | `object`, required | Current platform capacity. All values are 0 when the account has no active eligible plan. | | `limits.pump_fun` | `enum`, required | | | `limits.fomo_user` | `integer`, required | | | `limits.fomo_coin` | `enum`, required | | | `removed` | `boolean` | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `404` | The requested resource was not found | | | `409` | Platform subscription limit reached | | | `500` | The request could not be completed | | | `503` | Temporarily unavailable | | #### 200 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-fomo-and-callout-subscriptions#responses) #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 409 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request PUT \ --url https://api.tweetstream.io/api/callouts \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "platform": "pump_fun", "input": "marketdesk" }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/callouts", { method: "PUT", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "platform": "pump_fun", "input": "marketdesk" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.put( "https://api.tweetstream.io/api/callouts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "platform": "pump_fun", "input": "marketdesk", }, ) print(response.status_code, response.json()) ``` ## Remove a tracked or pending FOMO or pump.fun item DELETE /api/callouts stops tracking a FOMO or pump.fun item by callerId, or cancels a pending one by intentId, and returns the updated subscription list. Canonical URL: https://tweetstream.io/docs/api/remove-fomo-or-callout-subscription ### `DELETE /api/callouts` `https://api.tweetstream.io/api/callouts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `platform` | `enum`, required | | | `callerId` | `string`, required | | #### Body example ```json { "callerId": "marketdesk", "platform": "pump_fun" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `caller` | `object` | | | `caller.callerId` | `string`, required | | | `caller.createdAt` | `string`, required | | | `caller.label` | `string`, required | | | `caller.platform` | `enum`, required | | | `caller.username` | `string`, required | | | `caller.metadata` | `object` | | | `caller.metadata.displayName` | `string` | | | `caller.metadata.avatarUrl` | `string` | | | `caller.metadata.tokenAddress` | `string` | | | `caller.metadata.symbol` | `string` | | | `caller.metadata.name` | `string` | | | `caller.metadata.imageUrl` | `string` | | | `caller.metadata.networkId` | `integer` | | | `callers` | `object[] \| null`, required | | | `callers.callerId` | `string`, required | | | `callers.createdAt` | `string`, required | | | `callers.label` | `string`, required | | | `callers.platform` | `enum`, required | | | `callers.username` | `string`, required | | | `callers.metadata` | `object` | | | `callers.metadata.displayName` | `string` | | | `callers.metadata.avatarUrl` | `string` | | | `callers.metadata.tokenAddress` | `string` | | | `callers.metadata.symbol` | `string` | | | `callers.metadata.name` | `string` | | | `callers.metadata.imageUrl` | `string` | | | `callers.metadata.networkId` | `integer` | | | `pending` | `object[] \| null`, required | | | `pending.createdAt` | `string`, required | | | `pending.intentId` | `string`, required | | | `pending.input` | `string`, required | | | `pending.label` | `string`, required | | | `pending.platform` | `enum`, required | | | `limit` | `enum`, required | Current pump.fun capacity, the same as limits.pump_fun. Read limits for each platform's capacity. | | `limits` | `object`, required | Current platform capacity. All values are 0 when the account has no active eligible plan. | | `limits.pump_fun` | `enum`, required | | | `limits.fomo_user` | `integer`, required | | | `limits.fomo_coin` | `enum`, required | | | `removed` | `boolean` | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `404` | The requested resource was not found | | | `500` | The request could not be completed | | | `503` | Temporarily unavailable | | #### 200 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-fomo-and-callout-subscriptions#responses) #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request DELETE \ --url https://api.tweetstream.io/api/callouts \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "callerId": "marketdesk", "platform": "pump_fun" }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/callouts", { method: "DELETE", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "callerId": "marketdesk", "platform": "pump_fun" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.delete( "https://api.tweetstream.io/api/callouts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "callerId": "marketdesk", "platform": "pump_fun", }, ) print(response.status_code, response.json()) ``` ## Read authenticated account limits and usage GET /api/me returns the key's plan, monitored accounts and limit, open WebSocket connections and limit, and Ultra Speed usage when the plan includes it. Canonical URL: https://tweetstream.io/docs/api/get-account-status ### `GET /api/me` `https://api.tweetstream.io/api/me` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Response fields | Name | Type | Description | | --- | --- | --- | | `credentialScope` | `enum`, required | | | `plan` | `string`, required | | | `stripe` | `object`, required | | | `trackedAccounts` | `object`, required | | | `trackedAccounts.count` | `integer`, required | | | `trackedAccounts.handles` | `string[]`, required | | | `trackedAccounts.limit` | `integer`, required | | | `ultraSpeed` | `object`, required | | | `ultraSpeed.trackedAccounts` | `object`, required | | | `ultraSpeed.trackedAccounts.count` | `integer`, required | | | `ultraSpeed.trackedAccounts.handles` | `string[]`, required | | | `userId` | `string`, required | | | `websocket` | `object`, required | | | `websocket.count` | `integer`, required | | | `websocket.limit` | `integer`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `404` | The requested resource was not found | | | `500` | The request could not be completed | | #### 200 ```json { "credentialScope": "standard", "plan": "", "stripe": {}, "trackedAccounts": { "count": 0, "handles": [ "" ], "limit": 0 }, "ultraSpeed": { "trackedAccounts": { "count": 0, "handles": [ "" ] } }, "userId": "", "websocket": { "count": 0, "limit": 0 } } ``` #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://api.tweetstream.io/api/me \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/me", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://api.tweetstream.io/api/me", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, ) print(response.status_code, response.json()) ``` ## Remove monitored accounts Remove one or more monitored X/Twitter accounts. Canonical URL: https://tweetstream.io/docs/api/remove-accounts ### `DELETE /api/remove-account` `https://api.tweetstream.io/api/remove-account` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `accounts` | `string \| string[]`, required | | #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/add-accounts#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `action` | `enum`, required | | | `error` | `string \| null`, required | | | `requestId` | `string`, required | | | `results` | `object[]`, required | | | `results.input` | `string`, required | | | `results.message` | `string` | | | `results.state` | `enum`, required | | | `summary` | `object`, required | | | `summary.failed` | `integer`, required | | | `summary.succeeded` | `integer`, required | | | `summary.total` | `integer`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `207` | Some requested account operations succeeded and some failed | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `429` | Too many handle requests | `Retry-After` | | `500` | The request could not be completed | | | `503` | Account management is temporarily unavailable | | #### 200 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/add-accounts#responses) #### 207 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/add-accounts#responses) #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/add-accounts#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/add-accounts#responses) ### Code samples #### cURL ```bash curl --request DELETE \ --url https://api.tweetstream.io/api/remove-account \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "accounts": [ "marketdesk", "realDonaldTrump" ] }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/remove-account", { method: "DELETE", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "accounts": [ "marketdesk", "realDonaldTrump" ] }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.delete( "https://api.tweetstream.io/api/remove-account", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "accounts": [ "marketdesk", "realDonaldTrump", ], }, ) print(response.status_code, response.json()) ``` ## List Ultra Speed accounts List the accounts selected for Ultra Speed and the plan's account limit. Canonical URL: https://tweetstream.io/docs/api/list-ultra-accounts ### `GET /api/ultra/accounts` `https://api.tweetstream.io/api/ultra/accounts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Response fields | Name | Type | Description | | --- | --- | --- | | `accountLimit` | `integer`, required | an integer | | `accounts` | `object[]`, required | | | `accounts.handle` | `string`, required | a string matching the pattern ^@?[A-Za-z0-9_]{1,15}$ | | `accounts.id` | `string`, required | a string matching the pattern ^[1-9][0-9]{0,19}$ | | `subscriptionId` | `string`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `401` | Missing or invalid API key, or the setup proof is missing or expired | | | `404` | No such checkout or link, or the account has no entitlement for this product | | | `429` | Rate limit or activation budget reached; retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "accountLimit": 5, "accounts": [ { "handle": "marketdesk", "id": "1189745302" } ], "subscriptionId": "sub_1QExampleUltra" } ``` #### 401 ```json { "error": { "code": "INVALID_REQUEST", "message": "", "reason": "not_offered", "retryAfterSeconds": 123 }, "next": { "message": "", "action": "call_action", "method": "POST", "name": "", "url": "", "who": "agent" } } ``` #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://api.tweetstream.io/api/ultra/accounts \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/ultra/accounts", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://api.tweetstream.io/api/ultra/accounts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, ) print(response.status_code, response.json()) ``` ## Change Ultra Speed accounts Turn Ultra Speed on or off for accounts, each by handle. Canonical URL: https://tweetstream.io/docs/api/set-ultra-accounts ### `POST /api/ultra/accounts` `https://api.tweetstream.io/api/ultra/accounts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Headers | Name | Type | Description | | --- | --- | --- | | `Idempotency-Key` | `string`, required | Required. Generate one key per intended purchase or change and reuse it on retries; the same key returns the same result. | ### Body | Name | Type | Description | | --- | --- | --- | | `changes` | `object[]`, required | an array of at most 100 item(s) | | `changes.enabled` | `boolean`, required | | | `changes.handle` | `string`, required | a string matching the pattern ^@?[A-Za-z0-9_]{1,15}$ | | `subscriptionId` | `string`, required | a string at most 128 character(s) long | #### Body example ```json { "changes": [ { "enabled": true, "handle": "marketdesk" } ], "subscriptionId": "sub_1QExampleUltra" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `accountLimit` | `integer`, required | an integer | | `accounts` | `object[]`, required | | | `accounts.handle` | `string`, required | a string matching the pattern ^@?[A-Za-z0-9_]{1,15}$ | | `accounts.id` | `string`, required | a string matching the pattern ^[1-9][0-9]{0,19}$ | | `subscriptionId` | `string`, required | | | `results` | `object[]`, required | | | `results.enabled` | `boolean`, required | | | `results.handle` | `string`, required | a string matching the pattern ^@?[A-Za-z0-9_]{1,15}$ | | `results.message` | `string` | a string at most 200 character(s) long | | `results.outcome` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request, wrong code, or the Terms were not accepted | | | `401` | Missing or invalid API key, or the setup proof is missing or expired | | | `404` | No such checkout or link, or the account has no entitlement for this product | | | `409` | Idempotency, checkout, offer or trial conflict | | | `429` | Rate limit or activation budget reached; retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "accountLimit": 5, "accounts": [ { "handle": "marketdesk", "id": "1189745302" } ], "subscriptionId": "sub_1QExampleUltra", "results": [ { "enabled": true, "handle": "marketdesk", "outcome": "applied" } ] } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 409 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://api.tweetstream.io/api/ultra/accounts \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7' \ --header 'Content-Type: application/json' \ --data '{ "changes": [ { "enabled": true, "handle": "marketdesk" } ], "subscriptionId": "sub_1QExampleUltra" }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/ultra/accounts", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Idempotency-Key": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "Content-Type": "application/json", }, body: JSON.stringify({ "changes": [ { "enabled": true, "handle": "marketdesk" } ], "subscriptionId": "sub_1QExampleUltra" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://api.tweetstream.io/api/ultra/accounts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}", "Idempotency-Key": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}, json={ "changes": [ { "enabled": True, "handle": "marketdesk", }, ], "subscriptionId": "sub_1QExampleUltra", }, ) print(response.status_code, response.json()) ``` ## List watched Instagram accounts List the Instagram accounts on your watchlist and your account limit. Canonical URL: https://tweetstream.io/docs/api/list-instagram-accounts ### `GET /api/instagram/accounts` `https://api.tweetstream.io/api/instagram/accounts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Response fields | Name | Type | Description | | --- | --- | --- | | `accounts` | `object[]`, required | | | `accounts.username` | `string`, required | | | `accounts.state` | `enum`, required | `live`: watched now. `pending`: added, and watching starts shortly. `paused`: over your current limit, so not watched. | | `accounts.createdAt` | `string`, required | | | `limit` | `integer`, required | | | `websocketIncluded` | `boolean`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `500` | The request could not be completed | | | `503` | Instagram account management is temporarily unavailable | | #### 200 ```json { "accounts": [ { "username": "", "state": "live", "createdAt": "2026-01-01T00:00:00Z" } ], "limit": 0, "websocketIncluded": true } ``` #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://api.tweetstream.io/api/instagram/accounts \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/instagram/accounts", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://api.tweetstream.io/api/instagram/accounts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, ) print(response.status_code, response.json()) ``` ## Add watched Instagram accounts Add up to 100 Instagram accounts to your watchlist. Accounts already on it are reported as `duplicate` and count as success. Canonical URL: https://tweetstream.io/docs/api/add-instagram-accounts ### `POST /api/instagram/add-account` `https://api.tweetstream.io/api/instagram/add-account` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `accounts` | `string \| string[]`, required | Instagram usernames, with or without a leading `@`. | #### Body example ```json { "accounts": [ "nasa", "@natgeo" ] } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `accounts` | `object[]`, required | | | `accounts.username` | `string`, required | | | `accounts.state` | `enum`, required | `live`: watched now. `pending`: added, and watching starts shortly. `paused`: over your current limit, so not watched. | | `accounts.createdAt` | `string`, required | | | `limit` | `integer`, required | | | `rejected` | `object[]`, required | | | `rejected.username` | `string`, required | | | `rejected.reason` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `207` | Some requested accounts were changed and some were rejected | | | `400` | Invalid request, or every requested account was rejected | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `500` | The request could not be completed | | | `503` | Instagram account management is temporarily unavailable | | #### 200 ```json { "accounts": [ { "username": "", "state": "live", "createdAt": "2026-01-01T00:00:00Z" } ], "limit": 0, "rejected": [ { "username": "", "reason": "invalid" } ] } ``` #### 207 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/add-instagram-accounts#responses) #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/add-instagram-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://api.tweetstream.io/api/instagram/add-account \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "accounts": [ "nasa", "@natgeo" ] }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/instagram/add-account", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "accounts": [ "nasa", "@natgeo" ] }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://api.tweetstream.io/api/instagram/add-account", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "accounts": [ "nasa", "@natgeo", ], }, ) print(response.status_code, response.json()) ``` ## Remove watched Instagram accounts Remove up to 100 Instagram accounts from your watchlist. Accounts not on it are reported as `not_tracked` and count as success. Canonical URL: https://tweetstream.io/docs/api/remove-instagram-accounts ### `DELETE /api/instagram/remove-account` `https://api.tweetstream.io/api/instagram/remove-account` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `accounts` | `string \| string[]`, required | Instagram usernames, with or without a leading `@`. | #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/add-instagram-accounts#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `accounts` | `object[]`, required | | | `accounts.username` | `string`, required | | | `accounts.state` | `enum`, required | `live`: watched now. `pending`: added, and watching starts shortly. `paused`: over your current limit, so not watched. | | `accounts.createdAt` | `string`, required | | | `limit` | `integer`, required | | | `removed` | `string[]`, required | | | `rejected` | `object[]`, required | | | `rejected.username` | `string`, required | | | `rejected.reason` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `207` | Some requested accounts were changed and some were rejected | | | `400` | Invalid request, or every requested account was rejected | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `500` | The request could not be completed | | | `503` | Instagram account management is temporarily unavailable | | #### 200 ```json { "accounts": [ { "username": "", "state": "live", "createdAt": "2026-01-01T00:00:00Z" } ], "limit": 0, "removed": [ "" ], "rejected": [ { "username": "", "reason": "invalid" } ] } ``` #### 207 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/remove-instagram-accounts#responses) #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/remove-instagram-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request DELETE \ --url https://api.tweetstream.io/api/instagram/remove-account \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "accounts": [ "nasa", "@natgeo" ] }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/instagram/remove-account", { method: "DELETE", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "accounts": [ "nasa", "@natgeo" ] }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.delete( "https://api.tweetstream.io/api/instagram/remove-account", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "accounts": [ "nasa", "@natgeo", ], }, ) print(response.status_code, response.json()) ``` ## Read stored news articles GET /api/news/history returns stored articles from your enabled news sources, newest first, up to 100 per page. Page back with the cursor in nextCursor. Canonical URL: https://tweetstream.io/docs/api/get-news-history ### `GET /api/news/history` `https://api.tweetstream.io/api/news/history` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Query parameters | Name | Type | Description | | --- | --- | --- | | `before` | `string` | Cursor from the prior response, or an ISO date. | | `sourceId` | `string` | | | `limit` | `integer` | | ### Response fields | Name | Type | Description | | --- | --- | --- | | `data` | `object[]`, required | | | `data.author` | `string \| null`, required | | | `data.categories` | `string[]`, required | | | `data.content` | `string \| null`, required | | | `data.copyright` | `string \| null`, required | | | `data.description` | `string \| null`, required | | | `data.id` | `string`, required | | | `data.keywords` | `string[]`, required | | | `data.language` | `string \| null`, required | | | `data.media` | `object[]`, required | | | `data.modifiedAt` | `string \| null`, required | | | `data.primaryCategory` | `string \| null`, required | | | `data.publishedAt` | `string`, required | | | `data.receivedAt` | `string`, required | | | `data.source` | `object`, required | | | `data.source.id` | `string`, required | | | `data.source.name` | `string`, required | | | `data.summary` | `string \| null`, required | | | `data.title` | `string`, required | | | `data.url` | `string`, required | | | `metadata` | `object`, required | | | `metadata.count` | `integer`, required | | | `metadata.nextCursor` | `string \| null`, required | | | `metadata.sourceId` | `string` | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `429` | Rate limit reached | | | `500` | The request could not be completed | | #### 200 ```json { "data": [ { "id": "news_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "source": { "id": "bbc-news", "name": "BBC News" }, "url": "https://www.bbc.com/news/articles/example", "title": "Markets open after the holiday", "publishedAt": "2026-08-26T23:27:38.000Z", "receivedAt": "2026-08-26T23:27:38.123Z", "modifiedAt": null, "primaryCategory": "Business", "categories": [ "Business" ], "author": "BBC News", "keywords": [ "markets" ], "description": "A brief description supplied by the publication.", "summary": "Markets reopened after the holiday.", "media": [ { "url": "https://ichef.bbci.co.uk/news/example.jpg", "type": "image", "caption": "A market floor" } ], "content": "The stored article text, when available.", "language": "en", "copyright": "BBC" } ], "metadata": { "count": 1, "nextCursor": "v1.MTc4Nzc4Njg1ODEyMwpuZXdzXzAxMjM0NTY3ODlhYmNkZWYwMTIzNDU2Nzg5YWJjZGVmMDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY", "sourceId": "bbc-news" } } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://api.tweetstream.io/api/news/history \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/news/history", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://api.tweetstream.io/api/news/history", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, ) print(response.status_code, response.json()) ``` ## List news sources and current settings GET /api/news/sources lists every news source with its name and icon, whether it is available right now, and whether it is enabled for your stream. Canonical URL: https://tweetstream.io/docs/api/list-news-sources ### `GET /api/news/sources` `https://api.tweetstream.io/api/news/sources` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Response fields | Name | Type | Description | | --- | --- | --- | | `sources` | `object[]`, required | | | `sources.available` | `boolean`, required | | | `sources.enabled` | `boolean`, required | | | `sources.icon` | `string`, required | | | `sources.id` | `string`, required | | | `sources.name` | `string`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `500` | The request could not be completed | | #### 200 ```json { "sources": [ { "id": "bbc-news", "name": "BBC News", "icon": "/news-sources/bbc.png", "available": true, "enabled": true }, { "id": "dexerto", "name": "Dexerto", "icon": "/news-sources/dexerto.png", "available": true, "enabled": false } ] } ``` #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://api.tweetstream.io/api/news/sources \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/news/sources", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://api.tweetstream.io/api/news/sources", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, ) print(response.status_code, response.json()) ``` ## Enable or disable one news source PATCH /api/news/sources turns one news source on or off for your stream by sourceId. It returns the source; 409 means it is not available right now. Canonical URL: https://tweetstream.io/docs/api/set-news-source-enabled ### `PATCH /api/news/sources` `https://api.tweetstream.io/api/news/sources` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `enabled` | `boolean`, required | | | `sourceId` | `string`, required | | #### Body example ```json { "enabled": true, "sourceId": "bbc-news" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `source` | `object`, required | | | `source.available` | `boolean`, required | | | `source.enabled` | `boolean`, required | | | `source.icon` | `string`, required | | | `source.id` | `string`, required | | | `source.name` | `string`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request | | | `401` | Missing or invalid API key | | | `403` | The authenticated account cannot use this capability | | | `409` | The source is not currently available | | | `500` | The request could not be completed | | #### 200 ```json { "source": { "available": true, "enabled": true, "icon": "", "id": "", "name": "" } } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 409 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) #### 500 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-history#responses) ### Code samples #### cURL ```bash curl --request PATCH \ --url https://api.tweetstream.io/api/news/sources \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "enabled": true, "sourceId": "bbc-news" }' ``` #### JavaScript ```javascript const response = await fetch("https://api.tweetstream.io/api/news/sources", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "enabled": true, "sourceId": "bbc-news" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.patch( "https://api.tweetstream.io/api/news/sources", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "enabled": True, "sourceId": "bbc-news", }, ) print(response.status_code, response.json()) ``` ## Read the public catalog Plans, prices, limits and trials an agent can check out, with the default payment rail and billing cycle. No key needed. Canonical URL: https://tweetstream.io/docs/api/get-agent-catalog ### `GET /api/agent/catalog` `https://tweetstream.io/api/agent/catalog` ### Response fields | Name | Type | Description | | --- | --- | --- | | `currency` | `enum`, required | | | `defaults` | `object`, required | | | `defaults.billingCycle` | `enum`, required | | | `defaults.paymentRail` | `enum`, required | | | `families` | `object`, required | | | `families.BASE` | `object`, required | | | `families.BASE.plans` | `object[]`, required | | | `families.BASE.plans.limits` | `object`, required | | | `families.BASE.plans.name` | `string`, required | | | `families.BASE.plans.planType` | `enum`, required | | | `families.BASE.plans.prices` | `object[]`, required | | | `families.BASE.plans.trial` | `object`, required | | | `families.BASE.scale` | `object`, required | | | `families.BASE.scale.monitoredAccountLimit` | `object`, required | | | `families.BASE.scale.name` | `string`, required | | | `families.BASE.scale.planType` | `enum`, required | | | `families.BASE.scale.websocketLimit` | `object`, required | | | `families.INSTAGRAM` | `object`, required | | | `families.INSTAGRAM.tiers` | `object[]`, required | | | `families.INSTAGRAM.tiers.accountLimit` | `integer`, required | an integer | | `families.INSTAGRAM.tiers.prices` | `object[]`, required | | | `families.INSTAGRAM.tiers.websocketConnections` | `integer`, required | an integer | | `families.ULTRA` | `object`, required | | | `families.ULTRA.accountLimit` | `object`, required | | | `families.ULTRA.accountLimit.max` | `integer`, required | an integer | | `families.ULTRA.accountLimit.min` | `integer`, required | an integer | | `families.ULTRA.pricesPerAccount` | `object[]`, required | | | `families.ULTRA.pricesPerAccount.billingCycle` | `enum`, required | | | `families.ULTRA.pricesPerAccount.chargeMinor` | `string`, required | | | `families.ULTRA.websocketConnections` | `integer`, required | an integer | | `paymentRails` | `enum[]`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | #### 200 ```json { "currency": "USD", "defaults": { "billingCycle": "MONTHLY", "paymentRail": "CRYPTO" }, "families": { "BASE": { "plans": [ { "limits": { "monitoredAccounts": 123, "websocketConnections": 123 }, "name": "", "planType": "BASIC", "prices": [ { "billingCycle": "MONTHLY", "chargeMinor": "" } ], "trial": { "days": 123, "monitoredAccounts": 123, "websocketConnections": 123 } } ], "scale": { "monitoredAccountLimit": { "max": 123, "min": 123, "step": 123 }, "name": "", "planType": "ENTERPRISE", "websocketLimit": { "max": 123, "min": 123 } } }, "INSTAGRAM": { "tiers": [ { "accountLimit": 123, "prices": [ { "billingCycle": "MONTHLY", "chargeMinor": "" } ], "websocketConnections": 123 } ] }, "ULTRA": { "accountLimit": { "max": 123, "min": 123 }, "pricesPerAccount": [ { "billingCycle": "MONTHLY", "chargeMinor": "" } ], "websocketConnections": 123 } }, "paymentRails": [ "CRYPTO" ] } ``` ### Code samples #### cURL ```bash curl --request GET \ --url https://tweetstream.io/api/agent/catalog ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/catalog", { method: "GET", }); console.log(response.status, await response.json()); ``` #### Python ```python import requests response = requests.get( "https://tweetstream.io/api/agent/catalog", ) print(response.status_code, response.json()) ``` ## Start a checkout Start a checkout and get one payment page for the person to open. Crypto is the default rail; send paymentRail CARD for a card. A trial is used when the account still has one. The response's next step says what to do: open_payment (give the person paymentUrl, then poll pollUrl), join_discord, or wait. Replaying the same Idempotency-Key returns the same checkout. Canonical URL: https://tweetstream.io/docs/api/create-agent-checkout ### `POST /api/agent/checkout` `https://tweetstream.io/api/agent/checkout` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Headers | Name | Type | Description | | --- | --- | --- | | `Idempotency-Key` | `string`, required | Required. Generate one key per intended purchase or change and reuse it on retries; the same key returns the same result. | | `X-TweetStream-Setup-Proof` | `string` | Optional. The setupProof returned by email verification; when present, a Discord step includes its join URL. | ### Body | Name | Type | Description | | --- | --- | --- | | `billingCycle` | `enum` | | | `paymentRail` | `enum` | | | `trial` | `enum` | | | `family` | `enum`, required | | | `planType` | `enum`, required | | #### Body example ```json { "billingCycle": "MONTHLY", "paymentRail": "CRYPTO", "trial": "if_eligible", "family": "BASE", "planType": "BASIC" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `checkoutId` | `string` | a string matching the pattern ^pl_[a-z0-9]{1,64}$ | | `family` | `enum`, required | | | `next` | `object`, required | | | `next.message` | `string` | a string at most 500 character(s) long | | `next.action` | `enum`, required | | | `next.method` | `enum`, required | | | `next.url` | `string`, required | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | | `next.who` | `enum`, required | | | `offer` | `object` | | | `offer.amountDueNow` | `object`, required | | | `offer.amountDueNow.currency` | `enum`, required | | | `offer.amountDueNow.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `offer.mode` | `enum`, required | | | `offer.planName` | `string`, required | | | `offer.renewal` | `object`, required | | | `offer.renewal.amount` | `object`, required | | | `offer.renewal.amount.currency` | `enum`, required | | | `offer.renewal.amount.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `offer.renewal.at` | `string`, required | a string to be decoded into a Date | | `offer.renewal.billingCycle` | `enum`, required | | | `offer.renewal.thenAmount` | `object`, required | | | `offer.renewal.thenAmount.currency` | `enum`, required | | | `offer.renewal.thenAmount.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `paymentUrl` | `string` | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | | `reason` | `enum`, required | | | `status` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | A replay, the product is already ready, or the person must join Discord first | | | `201` | Checkout created | | | `202` | Checkout is being prepared; poll status | | | `400` | Invalid request, wrong code, or the Terms were not accepted | | | `401` | Missing or invalid API key, or the setup proof is missing or expired | | | `403` | The account is restricted, or the request carried a foreign Origin | | | `409` | Idempotency, checkout, offer or trial conflict | | | `429` | Rate limit or activation budget reached; retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "status": "community_required", "family": "BASE", "reason": "COMMUNITY_REQUIRED", "checkoutId": "pl_8k2m4q7x", "discord": { "url": "https://tweetstream.io/connect/discord/EXAMPLE_DISCORD_LINK", "expiresAt": "2026-10-29T13:00:00.000Z" }, "next": { "action": "join_discord", "who": "human", "url": "https://tweetstream.io/connect/discord/EXAMPLE_DISCORD_LINK", "pollUrl": "https://tweetstream.io/api/agent/status?checkoutId=pl_8k2m4q7x", "afterSeconds": 5 } } ``` #### 201 ```json { "status": "payment_required", "family": "BASE", "reason": "new", "checkoutId": "pl_8k2m4q7x", "offer": { "mode": "trial", "planName": "Pro", "amountDueNow": { "currency": "USD", "minor": "0" }, "renewal": { "amount": { "currency": "USD", "minor": "49900" }, "at": "2026-11-01T12:00:00.000Z", "billingCycle": "MONTHLY", "thenAmount": { "currency": "USD", "minor": "49900" } } }, "paymentUrl": "https://tweetstream.io/pay/EXAMPLE_PAYMENT_LINK", "next": { "action": "open_payment", "who": "human", "url": "https://tweetstream.io/pay/EXAMPLE_PAYMENT_LINK", "pollUrl": "https://tweetstream.io/api/agent/status?family=BASE", "afterSeconds": 5 } } ``` #### 202 ```json { "status": "processing", "family": "BASE", "checkoutId": "pl_8k2m4q7x", "next": { "action": "wait", "who": "agent", "pollUrl": "https://tweetstream.io/api/agent/status?checkoutId=pl_8k2m4q7x", "afterSeconds": 5 } } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 409 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/checkout \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7' \ --header 'Content-Type: application/json' \ --data '{ "billingCycle": "MONTHLY", "paymentRail": "CRYPTO", "trial": "if_eligible", "family": "BASE", "planType": "BASIC" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/checkout", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Idempotency-Key": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "Content-Type": "application/json", }, body: JSON.stringify({ "billingCycle": "MONTHLY", "paymentRail": "CRYPTO", "trial": "if_eligible", "family": "BASE", "planType": "BASIC" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/checkout", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}", "Idempotency-Key": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}, json={ "billingCycle": "MONTHLY", "paymentRail": "CRYPTO", "trial": "if_eligible", "family": "BASE", "planType": "BASIC", }, ) print(response.status_code, response.json()) ``` ## Read a stream key Read the stream key for a product the account is entitled to: the Standard key, or the separate Ultra Speed key. Store it in an environment variable; never put it in a URL or a log. Canonical URL: https://tweetstream.io/docs/api/get-agent-credential ### `POST /api/agent/credentials` `https://tweetstream.io/api/agent/credentials` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Headers | Name | Type | Description | | --- | --- | --- | | `X-TweetStream-Setup-Proof` | `string`, required | The setupProof returned by email verification. It lasts 30 minutes; after that, verify a new email code. | ### Body | Name | Type | Description | | --- | --- | --- | | `family` | `enum`, required | | #### Body example ```json { "family": "BASE" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `apiKey` | `string`, required | | | `createdAt` | `string`, required | a string to be decoded into a Date | | `credentialScope` | `enum`, required | | | `family` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request, wrong code, or the Terms were not accepted | | | `401` | Missing or invalid API key, or the setup proof is missing or expired | | | `403` | The account is restricted, or the request carried a foreign Origin | | | `404` | No such checkout or link, or the account has no entitlement for this product | | | `429` | Rate limit or activation budget reached; retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "apiKey": "", "createdAt": "2026-10-29T12:02:00.000Z", "credentialScope": "STANDARD", "family": "BASE" } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/credentials \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ --header 'Content-Type: application/json' \ --data '{ "family": "BASE" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/credentials", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "X-TweetStream-Setup-Proof": process.env.TWEETSTREAM_SETUP_PROOF, "Content-Type": "application/json", }, body: JSON.stringify({ "family": "BASE" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/credentials", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}", "X-TweetStream-Setup-Proof": os.environ["TWEETSTREAM_SETUP_PROOF"]}, json={ "family": "BASE", }, ) print(response.status_code, response.json()) ``` ## Rotate a stream key Replace an exposed stream key. The old key, and setup proofs issued for it, stop working at once; the response holds the new key once. A key alone can't rotate: send the setup proof from a recent email code. Not replayable: a retry with the old Standard key gets 401, so verify a new email code to read the key again. Canonical URL: https://tweetstream.io/docs/api/rotate-agent-credential ### `POST /api/agent/credentials/rotate` `https://tweetstream.io/api/agent/credentials/rotate` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Headers | Name | Type | Description | | --- | --- | --- | | `X-TweetStream-Setup-Proof` | `string`, required | The setupProof returned by email verification. It lasts 30 minutes; after that, verify a new email code. | ### Body | Name | Type | Description | | --- | --- | --- | | `family` | `enum`, required | | #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-agent-credential#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `apiKey` | `string`, required | | | `createdAt` | `string`, required | a string to be decoded into a Date | | `credentialScope` | `enum`, required | | | `family` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request, wrong code, or the Terms were not accepted | | | `401` | Missing or invalid API key, or the setup proof is missing or expired | | | `403` | The account is restricted, or the request carried a foreign Origin | | | `404` | No such checkout or link, or the account has no entitlement for this product | | | `429` | Rate limit or activation budget reached; retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-agent-credential#responses) #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/credentials/rotate \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ --header 'Content-Type: application/json' \ --data '{ "family": "BASE" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/credentials/rotate", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "X-TweetStream-Setup-Proof": process.env.TWEETSTREAM_SETUP_PROOF, "Content-Type": "application/json", }, body: JSON.stringify({ "family": "BASE" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/credentials/rotate", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}", "X-TweetStream-Setup-Proof": os.environ["TWEETSTREAM_SETUP_PROOF"]}, json={ "family": "BASE", }, ) print(response.status_code, response.json()) ``` ## Issue a Discord link Issue the Discord link the person opens to link Discord and join the TweetStream community. Some checkouts need it before payment; status says when. Canonical URL: https://tweetstream.io/docs/api/issue-agent-discord-link ### `POST /api/agent/discord-link` `https://tweetstream.io/api/agent/discord-link` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Headers | Name | Type | Description | | --- | --- | --- | | `X-TweetStream-Setup-Proof` | `string`, required | The setupProof returned by email verification. It lasts 30 minutes; after that, verify a new email code. | ### Body | Name | Type | Description | | --- | --- | --- | | `family` | `enum`, required | | #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-agent-credential#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `checkoutId` | `string` | a string matching the pattern ^pl_[a-z0-9]{1,64}$ | | `family` | `enum`, required | | | `next` | `object`, required | | | `next.message` | `string` | a string at most 500 character(s) long | | `next.action` | `enum`, required | | | `next.method` | `enum`, required | | | `next.url` | `string`, required | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | | `next.who` | `enum`, required | | | `offer` | `object` | | | `offer.amountDueNow` | `object`, required | | | `offer.amountDueNow.currency` | `enum`, required | | | `offer.amountDueNow.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `offer.mode` | `enum`, required | | | `offer.planName` | `string`, required | | | `offer.renewal` | `object`, required | | | `offer.renewal.amount` | `object`, required | | | `offer.renewal.amount.currency` | `enum`, required | | | `offer.renewal.amount.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `offer.renewal.at` | `string`, required | a string to be decoded into a Date | | `offer.renewal.billingCycle` | `enum`, required | | | `offer.renewal.thenAmount` | `object`, required | | | `offer.renewal.thenAmount.currency` | `enum`, required | | | `offer.renewal.thenAmount.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `paymentUrl` | `string` | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | | `reason` | `enum`, required | | | `status` | `enum`, required | | | `discord` | `object`, required | | | `discord.expiresAt` | `string`, required | a string to be decoded into a Date | | `discord.required` | `boolean`, required | Whether the open checkout waits for the person to join before it can be paid. | | `discord.url` | `string`, required | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request, wrong code, or the Terms were not accepted | | | `401` | Missing or invalid API key, or the setup proof is missing or expired | | | `403` | The account is restricted, or the request carried a foreign Origin | | | `404` | No such checkout or link, or the account has no entitlement for this product | | | `429` | Rate limit or activation budget reached; retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "status": "community_required", "family": "BASE", "reason": "COMMUNITY_REQUIRED", "checkoutId": "pl_8k2m4q7x", "discord": { "url": "https://tweetstream.io/connect/discord/EXAMPLE_DISCORD_LINK", "expiresAt": "2026-10-29T13:00:00.000Z", "required": true }, "next": { "action": "join_discord", "who": "human", "url": "https://tweetstream.io/connect/discord/EXAMPLE_DISCORD_LINK", "pollUrl": "https://tweetstream.io/api/agent/status?checkoutId=pl_8k2m4q7x", "afterSeconds": 5 } } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/discord-link \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ --header 'Content-Type: application/json' \ --data '{ "family": "BASE" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/discord-link", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "X-TweetStream-Setup-Proof": process.env.TWEETSTREAM_SETUP_PROOF, "Content-Type": "application/json", }, body: JSON.stringify({ "family": "BASE" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/discord-link", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}", "X-TweetStream-Setup-Proof": os.environ["TWEETSTREAM_SETUP_PROOF"]}, json={ "family": "BASE", }, ) print(response.status_code, response.json()) ``` ## Request an email code Email a 6-digit code to the person. The response is the same for new and existing accounts. Ask the person for the code; it never reaches the agent any other way. Canonical URL: https://tweetstream.io/docs/api/request-agent-email-code ### `POST /api/agent/email-code/request` `https://tweetstream.io/api/agent/email-code/request` ### Body | Name | Type | Description | | --- | --- | --- | | `email` | `string`, required | a string that will be trimmed | #### Body example ```json { "email": "person@example.com" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `challengeId` | `string`, required | a string matching the pattern ^[0-9a-f]{64}$ | | `expiresAt` | `string`, required | a string to be decoded into a Date | | `next` | `object`, required | | | `next.message` | `string` | a string at most 500 character(s) long | | `next.action` | `enum`, required | | | `next.method` | `enum`, required | | | `next.url` | `string`, required | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | | `next.who` | `enum`, required | | | `resendAt` | `string`, required | a string to be decoded into a Date | | `status` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `202` | Success | | | `400` | Invalid request, wrong code, or the Terms were not accepted | | | `403` | The account is restricted, or the request carried a foreign Origin | | | `429` | Rate limit or activation budget reached; retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 202 ```json { "status": "awaiting_email", "challengeId": "4f1c9e2a7b3d8065c1e4a9f27d3b5c8e0a6f1d2b9c4e7a3f5d8b0c6e2a9f1d47", "expiresAt": "2026-10-29T12:10:00.000Z", "resendAt": "2026-10-29T12:01:00.000Z", "next": { "action": "verify_email", "who": "human_then_agent", "method": "POST", "url": "https://tweetstream.io/api/agent/email-code/verify" } } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/email-code/request \ --header 'Content-Type: application/json' \ --data '{ "email": "person@example.com" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/email-code/request", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ "email": "person@example.com" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import requests response = requests.post( "https://tweetstream.io/api/agent/email-code/request", json={ "email": "person@example.com", }, ) print(response.status_code, response.json()) ``` ## Verify an email code Verify the code. Send acceptTerms true only after the person has read and agreed to https://tweetstream.io/terms. Returns the account's API key, shown once, and a setup proof that lasts 30 minutes. Canonical URL: https://tweetstream.io/docs/api/verify-agent-email-code ### `POST /api/agent/email-code/verify` `https://tweetstream.io/api/agent/email-code/verify` ### Body | Name | Type | Description | | --- | --- | --- | | `acceptTerms` | `boolean` | | | `challengeId` | `string`, required | a string matching the pattern ^[0-9a-f]{64}$ | | `code` | `string`, required | a string matching the pattern ^\d{6}$ | | `family` | `enum` | | #### Body example ```json { "acceptTerms": true, "challengeId": "4f1c9e2a7b3d8065c1e4a9f27d3b5c8e0a6f1d2b9c4e7a3f5d8b0c6e2a9f1d47", "code": "482913", "family": "BASE" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `checkoutId` | `string` | a string matching the pattern ^pl_[a-z0-9]{1,64}$ | | `family` | `enum`, required | | | `next` | `object`, required | | | `next.message` | `string` | a string at most 500 character(s) long | | `next.action` | `enum`, required | | | `next.method` | `enum`, required | | | `next.url` | `string`, required | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | | `next.who` | `enum`, required | | | `offer` | `object` | | | `offer.amountDueNow` | `object`, required | | | `offer.amountDueNow.currency` | `enum`, required | | | `offer.amountDueNow.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `offer.mode` | `enum`, required | | | `offer.planName` | `string`, required | | | `offer.renewal` | `object`, required | | | `offer.renewal.amount` | `object`, required | | | `offer.renewal.amount.currency` | `enum`, required | | | `offer.renewal.amount.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `offer.renewal.at` | `string`, required | a string to be decoded into a Date | | `offer.renewal.billingCycle` | `enum`, required | | | `offer.renewal.thenAmount` | `object`, required | | | `offer.renewal.thenAmount.currency` | `enum`, required | | | `offer.renewal.thenAmount.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `paymentUrl` | `string` | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | | `reason` | `enum`, required | | | `status` | `enum`, required | | | `apiKey` | `string`, required | | | `setupProof` | `string`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request, wrong code, or the Terms were not accepted | | | `403` | The account is restricted, or the request carried a foreign Origin | | | `429` | Rate limit or activation budget reached; retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "status": "payment_required", "family": "BASE", "reason": "new", "apiKey": "", "setupProof": "", "next": { "action": "create_checkout", "who": "agent", "method": "POST", "url": "https://tweetstream.io/api/agent/checkout" } } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/email-code/verify \ --header 'Content-Type: application/json' \ --data '{ "challengeId": "4f1c9e2a7b3d8065c1e4a9f27d3b5c8e0a6f1d2b9c4e7a3f5d8b0c6e2a9f1d47", "code": "482913" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/email-code/verify", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ "challengeId": "4f1c9e2a7b3d8065c1e4a9f27d3b5c8e0a6f1d2b9c4e7a3f5d8b0c6e2a9f1d47", "code": "482913" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import requests response = requests.post( "https://tweetstream.io/api/agent/email-code/verify", json={ "challengeId": "4f1c9e2a7b3d8065c1e4a9f27d3b5c8e0a6f1d2b9c4e7a3f5d8b0c6e2a9f1d47", "code": "482913", }, ) print(response.status_code, response.json()) ``` ## Discover the sandbox stream The free sandbox stream: its URL, the fixed account list, the operations it sends, its delay and its limits. Connect without a key. Canonical URL: https://tweetstream.io/docs/api/get-agent-sandbox ### `GET /api/agent/sandbox` `https://tweetstream.io/api/agent/sandbox` ### Response fields | Name | Type | Description | | --- | --- | --- | | `accounts` | `object[]`, required | | | `accounts.handle` | `string`, required | a string matching the pattern ^@?[A-Za-z0-9_]{1,15}$ | | `accounts.id` | `string`, required | a string matching the pattern ^[1-9][0-9]{0,19}$ | | `delaySeconds` | `integer`, required | an integer | | `limits` | `object`, required | | | `limits.connectionsPerClient` | `integer`, required | an integer | | `limits.sessionMinutes` | `integer`, required | an integer | | `next` | `object`, required | | | `next.message` | `string` | a string at most 500 character(s) long | | `next.action` | `enum`, required | | | `next.who` | `enum`, required | | | `operations` | `object[]`, required | | | `operations.channel` | `enum`, required | | | `operations.op` | `enum`, required | | | `status` | `enum`, required | | | `stream` | `object`, required | | | `stream.subprotocol` | `enum`, required | | | `stream.url` | `string`, required | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "accounts": [ { "id": "1395261244769112065", "handle": "_richardteng" }, { "id": "1470958472409792515", "handle": "a1lon9" }, { "id": "877807935493033984", "handle": "binance" }, { "id": "1400391752368992260", "handle": "binancewallet" }, { "id": "1451036242431262720", "handle": "binancezh" }, { "id": "973261472", "handle": "blknoiz06" }, { "id": "1052454006537314306", "handle": "bnbchain" }, { "id": "14379660", "handle": "brian_armstrong" }, { "id": "1389913567671975937", "handle": "cb_doge" }, { "id": "2259434528", "handle": "cobie" }, { "id": "574032254", "handle": "coinbase" }, { "id": "902926941413453824", "handle": "cz_binance" }, { "id": "2704294333", "handle": "deitaone" }, { "id": "44196397", "handle": "elonmusk" }, { "id": "1284052345668673536", "handle": "eth_cedric" }, { "id": "218406806", "handle": "fern" }, { "id": "20749410", "handle": "finkd" }, { "id": "3295423333", "handle": "firstsquawk" }, { "id": "1749114887807320064", "handle": "flapdotsh" }, { "id": "1816036559864619011", "handle": "fourdotmemezh" }, { "id": "1003840309166366721", "handle": "heyibinance" }, { "id": "2070631956824698880", "handle": "jensenhuang" }, { "id": "2478756618", "handle": "jerallaire" }, { "id": "18876842", "handle": "jessepollak" }, { "id": "902839045356744704", "handle": "justinsuntron" }, { "id": "1792724913528172544", "handle": "meadgod" }, { "id": "1309886201944473600", "handle": "mert" }, { "id": "636513296", "handle": "nikitabier" }, { "id": "1164750442787561474", "handle": "nina_rong" }, { "id": "4398626122", "handle": "openai" }, { "id": "5943622", "handle": "pmarca" }, { "id": "1261335549215989760", "handle": "polymarket" }, { "id": "2076794413284569089", "handle": "ponsdotfamily" }, { "id": "1622243071806128131", "handle": "pumpfun" }, { "id": "25073877", "handle": "realdonaldtrump" }, { "id": "1265037073", "handle": "robinhoodapp" }, { "id": "352518189", "handle": "robinhoodcrypto" }, { "id": "1605", "handle": "sama" }, { "id": "244647486", "handle": "saylor" }, { "id": "951329744804392960", "handle": "solana" }, { "id": "34743251", "handle": "spacex" }, { "id": "1755899659040555009", "handle": "theunipcs" }, { "id": "2327407569", "handle": "toly" }, { "id": "1200616796295847936", "handle": "unusual_whales" }, { "id": "295218901", "handle": "vitalikbuterin" }, { "id": "605700792", "handle": "vladtenev" }, { "id": "1387497871751196672", "handle": "watcherguru" }, { "id": "1879644163769335808", "handle": "whitehouse" }, { "id": "3012852462", "handle": "zachxbt" }, { "id": "18856867", "handle": "zerohedge" } ], "delaySeconds": 60, "limits": { "connectionsPerClient": 2, "sessionMinutes": 30 }, "next": { "action": "connect", "message": "Connect with the tweetstream.v1 subprotocol; no key is needed.", "who": "agent" }, "operations": [ { "channel": "tweet", "op": "content" }, { "channel": "tweet", "op": "update" }, { "channel": "tweet", "op": "meta" }, { "channel": "tweet", "op": "delete" }, { "channel": "tweet", "op": "pin" }, { "channel": "tweet", "op": "unpin" } ], "status": "ready", "stream": { "subprotocol": "tweetstream.v1", "url": "wss://sandbox.tweetstream.io/ws" } } ``` #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://tweetstream.io/api/agent/sandbox ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/sandbox", { method: "GET", }); console.log(response.status, await response.json()); ``` #### Python ```python import requests response = requests.get( "https://tweetstream.io/api/agent/sandbox", ) print(response.status_code, response.json()) ``` ## Start a Scale trial Start a Scale trial with a code from the TweetStream team. Canonical URL: https://tweetstream.io/docs/api/start-agent-scale-trial ### `POST /api/agent/scale-trial` `https://tweetstream.io/api/agent/scale-trial` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Headers | Name | Type | Description | | --- | --- | --- | | `Idempotency-Key` | `string`, required | Required. Generate one key per intended purchase or change and reuse it on retries; the same key returns the same result. | ### Body | Name | Type | Description | | --- | --- | --- | | `code` | `string`, required | a string at most 128 character(s) long | #### Body example ```json { "code": "SCALE-TRIAL-CODE" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `checkoutId` | `string` | a string matching the pattern ^pl_[a-z0-9]{1,64}$ | | `family` | `enum`, required | | | `next` | `object`, required | | | `next.message` | `string` | a string at most 500 character(s) long | | `next.action` | `enum`, required | | | `next.method` | `enum`, required | | | `next.url` | `string`, required | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | | `next.who` | `enum`, required | | | `offer` | `object` | | | `offer.amountDueNow` | `object`, required | | | `offer.amountDueNow.currency` | `enum`, required | | | `offer.amountDueNow.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `offer.mode` | `enum`, required | | | `offer.planName` | `string`, required | | | `offer.renewal` | `object`, required | | | `offer.renewal.amount` | `object`, required | | | `offer.renewal.amount.currency` | `enum`, required | | | `offer.renewal.amount.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `offer.renewal.at` | `string`, required | a string to be decoded into a Date | | `offer.renewal.billingCycle` | `enum`, required | | | `offer.renewal.thenAmount` | `object`, required | | | `offer.renewal.thenAmount.currency` | `enum`, required | | | `offer.renewal.thenAmount.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `paymentUrl` | `string` | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | | `reason` | `enum`, required | | | `status` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request, wrong code, or the Terms were not accepted | | | `401` | Missing or invalid API key, or the setup proof is missing or expired | | | `403` | The account is restricted, or the request carried a foreign Origin | | | `409` | Idempotency, checkout, offer or trial conflict | | | `429` | Rate limit or activation budget reached; retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "status": "ready", "family": "BASE", "access": { "kind": "trial", "through": "2026-11-01T12:00:00.000Z" }, "stream": { "url": "wss://ws-global.tweetstream.io/ws", "subprotocol": "tweetstream.v1", "credentialScope": "STANDARD" }, "next": { "action": "select_accounts", "who": "agent", "method": "POST", "url": "https://tweetstream.io/api/add-account" }, "optionalSteps": [ { "action": "issue_discord_link", "who": "agent", "method": "POST", "url": "https://tweetstream.io/api/agent/discord-link" } ] } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 409 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/scale-trial \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7' \ --header 'Content-Type: application/json' \ --data '{ "code": "SCALE-TRIAL-CODE" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/scale-trial", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Idempotency-Key": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "Content-Type": "application/json", }, body: JSON.stringify({ "code": "SCALE-TRIAL-CODE" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/scale-trial", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}", "Idempotency-Key": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}, json={ "code": "SCALE-TRIAL-CODE", }, ) print(response.status_code, response.json()) ``` ## Read onboarding status Progress for one product (family) or one checkout (checkoutId), with the next step. Send exactly one of the two. Poll after a human step at the interval in next.afterSeconds. Never carries a key or a Discord link. Canonical URL: https://tweetstream.io/docs/api/get-agent-status ### `GET /api/agent/status` `https://tweetstream.io/api/agent/status` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Query parameters | Name | Type | Description | | --- | --- | --- | | `family` | `enum` | | | `checkoutId` | `string` | | ### Response fields | Name | Type | Description | | --- | --- | --- | | `checkoutId` | `string` | a string matching the pattern ^pl_[a-z0-9]{1,64}$ | | `family` | `enum`, required | | | `next` | `object`, required | | | `next.message` | `string` | a string at most 500 character(s) long | | `next.action` | `enum`, required | | | `next.method` | `enum`, required | | | `next.url` | `string`, required | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | | `next.who` | `enum`, required | | | `offer` | `object` | | | `offer.amountDueNow` | `object`, required | | | `offer.amountDueNow.currency` | `enum`, required | | | `offer.amountDueNow.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `offer.mode` | `enum`, required | | | `offer.planName` | `string`, required | | | `offer.renewal` | `object`, required | | | `offer.renewal.amount` | `object`, required | | | `offer.renewal.amount.currency` | `enum`, required | | | `offer.renewal.amount.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `offer.renewal.at` | `string`, required | a string to be decoded into a Date | | `offer.renewal.billingCycle` | `enum`, required | | | `offer.renewal.thenAmount` | `object`, required | | | `offer.renewal.thenAmount.currency` | `enum`, required | | | `offer.renewal.thenAmount.minor` | `string`, required | a string matching the pattern ^(0\|[1-9][0-9]*)$ | | `paymentUrl` | `string` | a string matching the pattern ^(https\|wss):\/\/[^\s]+$ | | `reason` | `enum`, required | | | `status` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid request, wrong code, or the Terms were not accepted | | | `401` | Missing or invalid API key, or the setup proof is missing or expired | | | `403` | The account is restricted, or the request carried a foreign Origin | | | `404` | No such checkout or link, or the account has no entitlement for this product | | | `429` | Rate limit or activation budget reached; retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/start-agent-scale-trial#responses) #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request GET \ --url https://tweetstream.io/api/agent/status \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/status", { method: "GET", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, }, }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.get( "https://tweetstream.io/api/agent/status", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, ) print(response.status_code, response.json()) ``` ## List agent actions Every agent action: its name, tier, MCP tool and scope, and the JSON Schemas of its input and result. No key needed. Each action is also listed below as POST /api/agent/actions/{name}. Canonical URL: https://tweetstream.io/docs/api/list-agent-actions ### `GET /api/agent/actions` `https://tweetstream.io/api/agent/actions` ### Response fields | Name | Type | Description | | --- | --- | --- | | `actions` | `object[]`, required | | | `actions.cost` | `enum`, required | | | `actions.input` | `object`, required | | | `actions.mcp` | `object`, required | | | `actions.mcp.scope` | `string`, required | | | `actions.mcp.tool` | `string`, required | | | `actions.method` | `enum`, required | | | `actions.name` | `string`, required | | | `actions.output` | `object`, required | | | `actions.summary` | `string`, required | | | `actions.tier` | `enum`, required | | | `actions.url` | `string`, required | | | `tiers` | `object`, required | | | `tiers.confirm` | `string`, required | | | `tiers.read` | `string`, required | | | `tiers.recent` | `string`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | #### 200 ```json { "actions": [ { "cost": "read", "input": {}, "mcp": { "scope": "", "tool": "" }, "method": "POST", "name": "", "output": {}, "summary": "", "tier": "read", "url": "" } ], "tiers": { "confirm": "", "read": "", "recent": "" } } ``` ### Code samples #### cURL ```bash curl --request GET \ --url https://tweetstream.io/api/agent/actions ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions", { method: "GET", }); console.log(response.status, await response.json()); ``` #### Python ```python import requests response = requests.get( "https://tweetstream.io/api/agent/actions", ) print(response.status_code, response.json()) ``` ## discord_community Act on the account's Discord: join the community server with the linked Discord account, check verification, or send a test billing reminder. Needs a recent email-code sign-in. Tier recent: the API key and X-TweetStream-Setup-Proof from an email code verified in the last 30 minutes. The MCP tool of the same name needs the tweetstream:settings scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-discord-community ### `POST /api/agent/actions/discord_community` `https://tweetstream.io/api/agent/actions/discord_community` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Headers | Name | Type | Description | | --- | --- | --- | | `X-TweetStream-Setup-Proof` | `string`, required | The setupProof returned by email verification. It lasts 30 minutes; after that, verify a new email code. | ### Body | Name | Type | Description | | --- | --- | --- | | `kind` | `enum`, required | | #### Body example ```json { "kind": "join_linked" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `community` | `object`, required | | | `community.botInstalled` | `boolean`, required | | | `community.botInstallUrl` | `string`, required | | | `community.channelReady` | `boolean`, required | | | `community.communityInviteUrl` | `string`, required | | | `community.linked` | `boolean`, required | | | `community.membership` | `enum`, required | | | `community.multipleLinked` | `boolean`, required | | | `community.onboardingRequired` | `boolean`, required | | | `community.required` | `boolean`, required | Whether this account is asked to join the TweetStream Discord community. Only a checkout whose status is community_required waits for it. | | `community.verificationPending` | `boolean`, required | | | `community.verified` | `boolean`, required | | | `kind` | `enum`, required | | | `outcome` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key, or the setup proof is missing or expired (REVERIFY_EMAIL) | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "community": { "botInstalled": true, "botInstallUrl": "", "channelReady": true, "communityInviteUrl": "", "linked": true, "membership": "member", "multipleLinked": true, "onboardingRequired": true, "required": true, "verificationPending": true, "verified": true }, "kind": "join_linked", "outcome": "applied" } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/discord_community \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ --header 'Content-Type: application/json' \ --data '{ "kind": "join_linked" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/discord_community", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "X-TweetStream-Setup-Proof": process.env.TWEETSTREAM_SETUP_PROOF, "Content-Type": "application/json", }, body: JSON.stringify({ "kind": "join_linked" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/discord_community", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}", "X-TweetStream-Setup-Proof": os.environ["TWEETSTREAM_SETUP_PROOF"]}, json={ "kind": "join_linked", }, ) print(response.status_code, response.json()) ``` ## get_account Read the account: email, name, terms, referral code and credits, stream setup progress, and Discord community standing and notification settings. The email is masked (j***@example.com) unless the request carries a recent email-code sign-in. A section that could not be read is null and named in refusals. Tier read: the API key alone. The MCP tool of the same name needs the tweetstream:account scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-get-account ### `POST /api/agent/actions/get_account` `https://tweetstream.io/api/agent/actions/get_account` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Headers | Name | Type | Description | | --- | --- | --- | | `X-TweetStream-Setup-Proof` | `string` | Optional. The setupProof returned by email verification; when present, the account email is shown in full. | ### Body #### Body example ```json {} ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `discord` | `object`, required | | | `discord.billingDms` | `object`, required | | | `discord.billingDms.eligible` | `boolean`, required | | | `discord.billingDms.enabled` | `boolean`, required | | | `discord.community` | `object`, required | | | `discord.community.botInstalled` | `boolean`, required | | | `discord.community.channelReady` | `boolean`, required | | | `discord.community.linked` | `boolean`, required | | | `discord.community.membership` | `enum`, required | | | `discord.community.multipleLinked` | `boolean`, required | | | `discord.community.onboardingRequired` | `boolean`, required | | | `discord.community.required` | `boolean`, required | Whether this account is asked to join the TweetStream Discord community. Only a checkout whose status is community_required waits for it. | | `discord.community.verificationPending` | `boolean`, required | | | `discord.community.verified` | `boolean`, required | | | `discord.limitAlerts` | `boolean`, required | | | `email` | `string`, required | | | `name` | `string`, required | | | `realtimeSetup` | `object`, required | | | `realtimeSetup.standard` | `object`, required | | | `realtimeSetup.standard.firstAlertAt` | `string`, required | | | `realtimeSetup.standard.lastConnectedAt` | `string`, required | | | `realtimeSetup.ultra_speed` | `object`, required | | | `realtimeSetup.ultra_speed.firstAlertAt` | `string`, required | | | `realtimeSetup.ultra_speed.lastConnectedAt` | `string`, required | | | `referral` | `object`, required | | | `referral.canRefer` | `boolean`, required | | | `referral.code` | `string`, required | | | `referral.issuedThisYearCents` | `integer`, required | an integer | | `referral.nextCreditUseAt` | `string`, required | | | `referral.onHold` | `boolean`, required | | | `referral.pendingCreditsCents` | `integer`, required | an integer | | `referral.referrals` | `object[]`, required | | | `referral.referrals.amountCents` | `integer`, required | an integer | | `referral.referrals.createdAt` | `string`, required | a string to be decoded into a Date | | `referral.referrals.maturesAt` | `string`, required | | | `referral.referrals.status` | `enum`, required | | | `referral.successfulReferrals` | `integer`, required | an integer | | `referral.url` | `string`, required | | | `refusals` | `object[]`, required | | | `refusals.message` | `string`, required | | | `refusals.reason` | `enum`, required | | | `refusals.section` | `enum`, required | | | `terms` | `object`, required | | | `terms.acceptedAt` | `string`, required | | | `terms.acceptedVersion` | `string`, required | | | `terms.currentVersion` | `string`, required | | | `terms.needsAcceptance` | `boolean`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "discord": { "billingDms": { "eligible": true, "enabled": true }, "community": { "botInstalled": false, "channelReady": false, "linked": true, "membership": "member", "multipleLinked": false, "onboardingRequired": false, "required": false, "verificationPending": false, "verified": true }, "limitAlerts": true }, "email": "person@example.com", "name": "Market Desk", "realtimeSetup": { "standard": { "firstAlertAt": "2026-10-29T12:20:41.000Z", "lastConnectedAt": "2026-11-05T09:14:03.000Z" }, "ultra_speed": { "firstAlertAt": null, "lastConnectedAt": null } }, "referral": { "canRefer": true, "code": "MARKETDESK", "issuedThisYearCents": 0, "nextCreditUseAt": null, "onHold": false, "pendingCreditsCents": 0, "referrals": [], "successfulReferrals": 0, "url": "https://tweetstream.io/signup?ref=MARKETDESK" }, "refusals": [], "terms": { "acceptedAt": "2026-10-29T12:02:00.000Z", "acceptedVersion": "2026-09-28", "currentVersion": "2026-09-28", "needsAcceptance": false } } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/get_account \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{}' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/get_account", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({}), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/get_account", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={}, ) print(response.status_code, response.json()) ``` ## update_account Change the account itself: set its name, apply another account's referral code, and turn Discord billing reminders and limit alerts on or off. Each change is applied or refused on its own. Needs a recent email-code sign-in. Tier recent: the API key and X-TweetStream-Setup-Proof from an email code verified in the last 30 minutes. The MCP tool of the same name needs the tweetstream:settings scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-update-account ### `POST /api/agent/actions/update_account` `https://tweetstream.io/api/agent/actions/update_account` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Headers | Name | Type | Description | | --- | --- | --- | | `X-TweetStream-Setup-Proof` | `string`, required | The setupProof returned by email verification. It lasts 30 minutes; after that, verify a new email code. | ### Body | Name | Type | Description | | --- | --- | --- | | `changes` | `object[]`, required | an array of at most 10 item(s) | | `changes.kind` | `enum`, required | | | `changes.name` | `string`, required | Surrounding spaces are dropped. | #### Body example ```json { "changes": [ { "kind": "name", "name": "Market Desk" } ] } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `results` | `object[]`, required | | | `results.kind` | `enum`, required | | | `results.outcome` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key, or the setup proof is missing or expired (REVERIFY_EMAIL) | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "results": [ { "kind": "name", "outcome": "applied" } ] } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/update_account \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ --header 'Content-Type: application/json' \ --data '{ "changes": [ { "kind": "name", "name": "Market Desk" } ] }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/update_account", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "X-TweetStream-Setup-Proof": process.env.TWEETSTREAM_SETUP_PROOF, "Content-Type": "application/json", }, body: JSON.stringify({ "changes": [ { "kind": "name", "name": "Market Desk" } ] }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/update_account", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}", "X-TweetStream-Setup-Proof": os.environ["TWEETSTREAM_SETUP_PROOF"]}, json={ "changes": [ { "kind": "name", "name": "Market Desk", }, ], }, ) print(response.status_code, response.json()) ``` ## cancel_pending_payment Prepare to cancel a family's open stablecoin payment, Scale's scheduled limit change, or Ultra Speed's open checkout. Nothing changes until confirm_action runs it with the code emailed to the person. Tier confirm: the call only holds the change and returns it. request_confirmation_code emails the person a code; confirm_action runs the change once they read it back. The MCP tool of the same name needs the tweetstream:billing scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-cancel-pending-payment ### `POST /api/agent/actions/cancel_pending_payment` `https://tweetstream.io/api/agent/actions/cancel_pending_payment` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `family` | `enum`, required | | | `target` | `enum`, required | open_payment: the family's open stablecoin payment request. scale_limit_change: Scale's scheduled limit change. open_checkout: Ultra Speed's open checkout. | #### Body example ```json { "family": "BASE", "target": "open_payment" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `next` | `object`, required | | | `next.action` | `enum`, required | | | `next.message` | `string`, required | | | `next.name` | `string`, required | | | `next.who` | `enum`, required | | | `pendingAction` | `object`, required | | | `pendingAction.action` | `string`, required | | | `pendingAction.expiresAt` | `string`, required | a string to be decoded into a Date | | `pendingAction.id` | `string`, required | | | `pendingAction.quote` | `object`, required | | | `pendingAction.quote.amountDueCents` | `integer`, required | an integer | | `pendingAction.quote.effectiveAt` | `string`, required | a string to be decoded into a Date | | `pendingAction.quote.renewal` | `object`, required | | | `pendingAction.quote.renewal.amountCents` | `integer`, required | an integer | | `pendingAction.quote.renewal.at` | `string`, required | a string to be decoded into a Date | | `pendingAction.quote.renewal.termMonths` | `integer`, required | an integer | | `pendingAction.quote.saveOffer` | `object`, required | | | `pendingAction.quote.saveOffer.description` | `string`, required | | | `pendingAction.quote.saveOffer.offer` | `object`, required | | | `pendingAction.summary` | `string`, required | | | `status` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `409` | Nothing to change, or the change is not offered (ACTION_REFUSED with reason) | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "next": { "action": "call_action", "message": "Show the person this change. If they want it, call request_confirmation_code to email them a code.", "name": "request_confirmation_code", "who": "agent" }, "pendingAction": { "action": "cancel_pending_payment", "expiresAt": "2026-11-05T12:05:00.000Z", "id": "pa_7Rk2mQ9xL4", "quote": { "amountDueCents": 0, "effectiveAt": "2026-11-05T12:05:00.000Z", "renewal": null, "saveOffer": null }, "summary": "Cancel the unpaid 199 USDC stablecoin payment for your TweetStream plan. Takes effect at once. Nothing is charged now." }, "status": "confirmation_required" } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 409 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/cancel_pending_payment \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "family": "BASE", "target": "open_payment" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/cancel_pending_payment", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "family": "BASE", "target": "open_payment" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/cancel_pending_payment", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "family": "BASE", "target": "open_payment", }, ) print(response.status_code, response.json()) ``` ## change_billing Prepare a change to a subscription: plan, term, Instagram or Ultra Speed account limit, pause, cancel (its quote names any save offer), a save offer, resume, keep, or auto-renew off. Returns the price and date; nothing changes until confirm_action runs it with the code emailed to the person. Tier confirm: the call only holds the change and returns it. request_confirmation_code emails the person a code; confirm_action runs the change once they read it back. The MCP tool of the same name needs the tweetstream:billing scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-change-billing ### `POST /api/agent/actions/change_billing` `https://tweetstream.io/api/agent/actions/change_billing` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `change` | `object`, required | | | `change.billingCycle` | `enum`, required | | | `change.kind` | `enum`, required | | | `change.plan` | `enum`, required | | | `family` | `enum`, required | | #### Body example ```json { "change": { "billingCycle": "MONTHLY", "kind": "change_plan", "plan": "BASIC" }, "family": "BASE" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `next` | `object`, required | | | `next.action` | `enum`, required | | | `next.message` | `string`, required | | | `next.name` | `string`, required | | | `next.who` | `enum`, required | | | `pendingAction` | `object`, required | | | `pendingAction.action` | `string`, required | | | `pendingAction.expiresAt` | `string`, required | a string to be decoded into a Date | | `pendingAction.id` | `string`, required | | | `pendingAction.quote` | `object`, required | | | `pendingAction.quote.amountDueCents` | `integer`, required | an integer | | `pendingAction.quote.effectiveAt` | `string`, required | a string to be decoded into a Date | | `pendingAction.quote.renewal` | `object`, required | | | `pendingAction.quote.renewal.amountCents` | `integer`, required | an integer | | `pendingAction.quote.renewal.at` | `string`, required | a string to be decoded into a Date | | `pendingAction.quote.renewal.termMonths` | `integer`, required | an integer | | `pendingAction.quote.saveOffer` | `object`, required | | | `pendingAction.quote.saveOffer.description` | `string`, required | | | `pendingAction.quote.saveOffer.offer` | `object`, required | | | `pendingAction.summary` | `string`, required | | | `status` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `409` | Nothing to change, or the change is not offered (ACTION_REFUSED with reason) | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "next": { "action": "call_action", "message": "Show the person this change. If they want it, call request_confirmation_code to email them a code.", "name": "request_confirmation_code", "who": "agent" }, "pendingAction": { "action": "change_billing", "expiresAt": "2026-11-05T12:05:00.000Z", "id": "pa_7Rk2mQ9xL4", "quote": { "amountDueCents": 0, "effectiveAt": "2026-11-29T12:00:00.000Z", "renewal": { "amountCents": 19900, "at": "2026-11-29T12:00:00.000Z", "termMonths": 1 }, "saveOffer": null }, "summary": "Change your plan to Minimum, billed monthly. Takes effect Nov 29, 2026. Nothing is charged now." }, "status": "confirmation_required" } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 409 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/change_billing \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "change": { "billingCycle": "MONTHLY", "kind": "change_plan", "plan": "BASIC" }, "family": "BASE" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/change_billing", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "change": { "billingCycle": "MONTHLY", "kind": "change_plan", "plan": "BASIC" }, "family": "BASE" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/change_billing", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "change": { "billingCycle": "MONTHLY", "kind": "change_plan", "plan": "BASIC", }, "family": "BASE", }, ) print(response.status_code, response.json()) ``` ## change_renewal_rail Change how a subscription's renewals are paid: CARD or CRYPTO (stablecoins). A payment due now comes back as a link the person opens. Needs a recent email-code sign-in. Tier recent: the API key and X-TweetStream-Setup-Proof from an email code verified in the last 30 minutes. The MCP tool of the same name needs the tweetstream:billing scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-change-renewal-rail ### `POST /api/agent/actions/change_renewal_rail` `https://tweetstream.io/api/agent/actions/change_renewal_rail` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Headers | Name | Type | Description | | --- | --- | --- | | `X-TweetStream-Setup-Proof` | `string`, required | The setupProof returned by email verification. It lasts 30 minutes; after that, verify a new email code. | ### Body | Name | Type | Description | | --- | --- | --- | | `family` | `enum`, required | | | `paymentRail` | `enum`, required | | #### Body example ```json { "family": "BASE", "paymentRail": "CRYPTO" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `outcome` | `enum`, required | | | `paymentRail` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key, or the setup proof is missing or expired (REVERIFY_EMAIL) | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "outcome": "updated", "paymentRail": "CRYPTO" } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/change_renewal_rail \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ --header 'Content-Type: application/json' \ --data '{ "family": "BASE", "paymentRail": "CRYPTO" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/change_renewal_rail", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "X-TweetStream-Setup-Proof": process.env.TWEETSTREAM_SETUP_PROOF, "Content-Type": "application/json", }, body: JSON.stringify({ "family": "BASE", "paymentRail": "CRYPTO" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/change_renewal_rail", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}", "X-TweetStream-Setup-Proof": os.environ["TWEETSTREAM_SETUP_PROOF"]}, json={ "family": "BASE", "paymentRail": "CRYPTO", }, ) print(response.status_code, response.json()) ``` ## get_billing Read each subscription's plan, price, status, renewal and the changes it offers, the open and recent stablecoin payments, and any open checkout. Tier read: the API key alone. The MCP tool of the same name needs the tweetstream:account scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-get-billing ### `POST /api/agent/actions/get_billing` `https://tweetstream.io/api/agent/actions/get_billing` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/agent-action-get-account#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `openCheckouts` | `object[]`, required | | | `openCheckouts.canCancel` | `boolean`, required | | | `openCheckouts.expiresAt` | `string`, required | a string to be decoded into a Date | | `openCheckouts.family` | `enum`, required | | | `openCheckouts.rail` | `enum`, required | | | `openCheckouts.state` | `enum`, required | | | `openPayments` | `object[]`, required | | | `openPayments.amount` | `string`, required | | | `openPayments.canCancel` | `boolean`, required | | | `openPayments.cancelEndsSubscription` | `boolean`, required | | | `openPayments.canPayByCard` | `boolean`, required | | | `openPayments.expiresAt` | `string`, required | a string to be decoded into a Date | | `openPayments.family` | `enum`, required | | | `openPayments.kind` | `enum`, required | | | `openPayments.state` | `enum`, required | | | `openPayments.underReview` | `boolean`, required | | | `recentPayments` | `object[]`, required | | | `recentPayments.amount` | `string`, required | | | `recentPayments.createdAt` | `string`, required | a string to be decoded into a Date | | `recentPayments.family` | `enum`, required | | | `recentPayments.kind` | `enum`, required | | | `recentPayments.method` | `string`, required | | | `recentPayments.status` | `enum`, required | | | `recentPayments.statusLabel` | `string`, required | | | `subscriptions` | `object[]`, required | | | `subscriptions.autoRenew` | `enum`, required | | | `subscriptions.availableChanges` | `enum[]`, required | | | `subscriptions.cancelAtPeriodEnd` | `boolean`, required | | | `subscriptions.family` | `enum`, required | | | `subscriptions.openPayment` | `object`, required | | | `subscriptions.openPayment.amountCents` | `number`, required | | | `subscriptions.openPayment.dueAt` | `string`, required | | | `subscriptions.openPayment.kind` | `enum`, required | | | `subscriptions.paidThrough` | `string`, required | | | `subscriptions.pause` | `object`, required | | | `subscriptions.pause.resumesAt` | `string`, required | a string to be decoded into a Date | | `subscriptions.pause.startsAt` | `string`, required | | | `subscriptions.pause.state` | `enum`, required | | | `subscriptions.periodEnd` | `string`, required | | | `subscriptions.plan` | `string`, required | | | `subscriptions.priceCents` | `number`, required | | | `subscriptions.rail` | `enum`, required | | | `subscriptions.renewalPaymentPreparable` | `boolean`, required | | | `subscriptions.scheduledTermChange` | `object`, required | | | `subscriptions.scheduledTermChange.effectiveAt` | `string`, required | a string to be decoded into a Date | | `subscriptions.scheduledTermChange.termMonths` | `number`, required | | | `subscriptions.state` | `enum`, required | | | `subscriptions.status` | `enum`, required | | | `subscriptions.statusDetail` | `object`, required | | | `subscriptions.statusDetail.amountCents` | `number`, required | | | `subscriptions.statusDetail.at` | `string`, required | | | `subscriptions.statusDetail.kind` | `enum`, required | | | `subscriptions.termMonths` | `number`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "openCheckouts": [], "openPayments": [], "recentPayments": [], "subscriptions": [ { "autoRenew": "on", "availableChanges": [], "cancelAtPeriodEnd": false, "family": "BASE", "openPayment": null, "paidThrough": "2026-11-29T12:00:00.000Z", "pause": null, "periodEnd": "2026-11-29T12:00:00.000Z", "plan": "Pro", "priceCents": 49900, "rail": "CARD", "renewalPaymentPreparable": false, "scheduledTermChange": null, "state": "card_active", "status": "active", "statusDetail": { "amountCents": 49900, "at": "2026-11-29T12:00:00.000Z", "kind": "renews" }, "termMonths": 1 } ] } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/get_billing \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{}' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/get_billing", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({}), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/get_billing", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={}, ) print(response.status_code, response.json()) ``` ## get_billing_portal_link A link to the billing portal, where the person manages their card and invoices. Needs a recent email-code sign-in. Tier recent: the API key and X-TweetStream-Setup-Proof from an email code verified in the last 30 minutes. The MCP tool of the same name needs the tweetstream:billing scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-get-billing-portal-link ### `POST /api/agent/actions/get_billing_portal_link` `https://tweetstream.io/api/agent/actions/get_billing_portal_link` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Headers | Name | Type | Description | | --- | --- | --- | | `X-TweetStream-Setup-Proof` | `string`, required | The setupProof returned by email verification. It lasts 30 minutes; after that, verify a new email code. | ### Body #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/agent-action-get-account#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `outcome` | `enum`, required | | | `url` | `string`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key, or the setup proof is missing or expired (REVERIFY_EMAIL) | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "outcome": "link", "url": "" } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/get_billing_portal_link \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header "X-TweetStream-Setup-Proof: $TWEETSTREAM_SETUP_PROOF" \ --header 'Content-Type: application/json' \ --data '{}' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/get_billing_portal_link", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "X-TweetStream-Setup-Proof": process.env.TWEETSTREAM_SETUP_PROOF, "Content-Type": "application/json", }, body: JSON.stringify({}), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/get_billing_portal_link", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}", "X-TweetStream-Setup-Proof": os.environ["TWEETSTREAM_SETUP_PROOF"]}, json={}, ) print(response.status_code, response.json()) ``` ## get_payment_link A link the person opens to pay what a subscription owes: its open invoice, its renewal in stablecoins, or, by card, an invoice waiting on a stablecoin payment. Tier read: the API key alone. The MCP tool of the same name needs the tweetstream:billing scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-get-payment-link ### `POST /api/agent/actions/get_payment_link` `https://tweetstream.io/api/agent/actions/get_payment_link` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `family` | `enum`, required | | | `target` | `enum`, required | invoice: the open card invoice. renewal: the stablecoin payment of the open renewal. outstanding_invoice_card: pay by card an invoice waiting on a stablecoin payment. | #### Body example ```json { "family": "BASE", "target": "invoice" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `expiresAt` | `string`, required | | | `outcome` | `enum`, required | | | `url` | `string`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "expiresAt": "2026-11-06T12:00:00.000Z", "outcome": "link", "url": "https://tweetstream.io/pay/EXAMPLE_PAYMENT_LINK" } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/get_payment_link \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "family": "BASE", "target": "invoice" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/get_payment_link", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "family": "BASE", "target": "invoice" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/get_payment_link", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "family": "BASE", "target": "invoice", }, ) print(response.status_code, response.json()) ``` ## confirm_action Run a held change once the person reads back the 6-digit code emailed for it. Calling it again returns the same outcome without running the change again. Tier confirm: the call only holds the change and returns it. request_confirmation_code emails the person a code; confirm_action runs the change once they read it back. The MCP tool of the same name needs the tweetstream:billing scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-confirm-action ### `POST /api/agent/actions/confirm_action` `https://tweetstream.io/api/agent/actions/confirm_action` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `challengeId` | `string` | a string at most 128 character(s) long | | `code` | `string` | a string matching the pattern ^\d{6}$ | | `pendingActionId` | `string`, required | a string at most 64 character(s) long | #### Body example ```json { "challengeId": "c2f8a1d4e7b03956", "code": "482913", "pendingActionId": "pa_7Rk2mQ9xL4" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `action` | `enum`, required | | | `outcome` | `object`, required | | | `outcome.chargedCents` | `number` | | | `outcome.effectiveAt` | `string`, required | a string to be decoded into a Date | | `outcome.kind` | `enum`, required | | | `outcome.refund` | `enum` | | | `pendingActionId` | `string`, required | | | `status` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | Invalid input, or the code is wrong (INVALID_CODE) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `404` | No held change with that pendingActionId for this API key (CONFIRMATION_NOT_FOUND) | | | `409` | The held change expired (CONFIRMATION_EXPIRED) | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "action": "cancel_pending_payment", "outcome": { "chargedCents": 123.45, "effectiveAt": "", "kind": "applied", "refund": "credit" }, "pendingActionId": "", "status": "completed" } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 409 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/confirm_action \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "pendingActionId": "pa_7Rk2mQ9xL4" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/confirm_action", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "pendingActionId": "pa_7Rk2mQ9xL4" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/confirm_action", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "pendingActionId": "pa_7Rk2mQ9xL4", }, ) print(response.status_code, response.json()) ``` ## get_pending_action Read a held change: what it does, whether a code was sent, and, once confirmed, its outcome. pendingActionId is the id a held change returned. A confirmed change with no outcome yet finishes when confirm_action is called again. Tier read: the API key alone. The MCP tool of the same name needs the tweetstream:billing scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-get-pending-action ### `POST /api/agent/actions/get_pending_action` `https://tweetstream.io/api/agent/actions/get_pending_action` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `pendingActionId` | `string`, required | a string at most 64 character(s) long | #### Body example ```json { "pendingActionId": "pa_7Rk2mQ9xL4" } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `outcome` | `object`, required | | | `outcome.chargedCents` | `number` | | | `outcome.effectiveAt` | `string`, required | a string to be decoded into a Date | | `outcome.kind` | `enum`, required | | | `outcome.refund` | `enum` | | | `pendingAction` | `object`, required | | | `pendingAction.action` | `string`, required | | | `pendingAction.expiresAt` | `string`, required | a string to be decoded into a Date | | `pendingAction.id` | `string`, required | | | `pendingAction.quote` | `object`, required | | | `pendingAction.quote.amountDueCents` | `integer`, required | an integer | | `pendingAction.quote.effectiveAt` | `string`, required | a string to be decoded into a Date | | `pendingAction.quote.renewal` | `object`, required | | | `pendingAction.quote.renewal.amountCents` | `integer`, required | an integer | | `pendingAction.quote.renewal.at` | `string`, required | a string to be decoded into a Date | | `pendingAction.quote.renewal.termMonths` | `integer`, required | an integer | | `pendingAction.quote.saveOffer` | `object`, required | | | `pendingAction.quote.saveOffer.description` | `string`, required | | | `pendingAction.quote.saveOffer.offer` | `object`, required | | | `pendingAction.summary` | `string`, required | | | `status` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `404` | No held change with that pendingActionId for this API key (CONFIRMATION_NOT_FOUND) | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "outcome": null, "pendingAction": { "action": "change_billing", "expiresAt": "2026-11-05T12:05:00.000Z", "id": "pa_7Rk2mQ9xL4", "quote": { "amountDueCents": 0, "effectiveAt": "2026-11-29T12:00:00.000Z", "renewal": { "amountCents": 19900, "at": "2026-11-29T12:00:00.000Z", "termMonths": 1 }, "saveOffer": null }, "summary": "Change your plan to Minimum, billed monthly. Takes effect Nov 29, 2026. Nothing is charged now." }, "status": "code_sent" } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/get_pending_action \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "pendingActionId": "pa_7Rk2mQ9xL4" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/get_pending_action", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "pendingActionId": "pa_7Rk2mQ9xL4" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/get_pending_action", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "pendingActionId": "pa_7Rk2mQ9xL4", }, ) print(response.status_code, response.json()) ``` ## request_confirmation_code Email the person a 6-digit code for one held change, naming the change, its price and its date. The code expires with the held change; asking again replaces the earlier code. Tier read: the API key alone. The MCP tool of the same name needs the tweetstream:billing scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-request-confirmation-code ### `POST /api/agent/actions/request_confirmation_code` `https://tweetstream.io/api/agent/actions/request_confirmation_code` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `pendingActionId` | `string`, required | a string at most 64 character(s) long | #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/agent-action-get-pending-action#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `challengeId` | `string`, required | | | `expiresAt` | `string`, required | a string to be decoded into a Date | | `next` | `object`, required | | | `next.action` | `enum`, required | | | `next.message` | `string`, required | | | `next.name` | `string`, required | | | `next.who` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `404` | No held change with that pendingActionId for this API key (CONFIRMATION_NOT_FOUND) | | | `409` | The held change expired (CONFIRMATION_EXPIRED) or is already confirmed (ACTION_REFUSED) | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "challengeId": "c2f8a1d4e7b03956", "expiresAt": "2026-11-05T12:15:00.000Z", "next": { "action": "call_action", "message": "Ask the person for the 6-digit code we emailed them, then call confirm_action.", "name": "confirm_action", "who": "human_then_agent" } } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 404 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 409 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/request_confirmation_code \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "pendingActionId": "pa_7Rk2mQ9xL4" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/request_confirmation_code", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "pendingActionId": "pa_7Rk2mQ9xL4" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/request_confirmation_code", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "pendingActionId": "pa_7Rk2mQ9xL4", }, ) print(response.status_code, response.json()) ``` ## get_accounts Read the accounts a product streams: the X watchlist with each account's settings (BASE), the Ultra Speed selection (ULTRA), or the Instagram watchlist (INSTAGRAM). Tier read: the API key alone. The MCP tool of the same name needs the tweetstream:account scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-get-accounts ### `POST /api/agent/actions/get_accounts` `https://tweetstream.io/api/agent/actions/get_accounts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `family` | `enum`, required | | #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/get-agent-credential#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `accounts` | `object[]`, required | | | `accounts.affiliateAlerts` | `object`, required | | | `accounts.affiliateAlerts.available` | `boolean`, required | | | `accounts.affiliateAlerts.enabled` | `boolean`, required | | | `accounts.disabledEventTypes` | `string[]`, required | | | `accounts.discordWebhook` | `object`, required | Present when a Discord webhook is saved; endsWith is the last 4 characters of its URL. | | `accounts.discordWebhook.configured` | `enum`, required | | | `accounts.discordWebhook.endsWith` | `string`, required | | | `accounts.handle` | `string`, required | | | `accounts.id` | `string`, required | | | `accounts.keywords` | `string[]`, required | | | `accounts.name` | `string`, required | | | `accounts.scope` | `enum`, required | | | `accounts.trialActive` | `boolean`, required | | | `accounts.twitterUserId` | `string`, required | | | `family` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "accounts": [ { "affiliateAlerts": { "available": true, "enabled": true }, "disabledEventTypes": [ "" ], "discordWebhook": { "configured": true, "endsWith": "" }, "handle": "", "id": "", "keywords": [ "" ], "name": "", "scope": "standard", "trialActive": true, "twitterUserId": "" } ], "family": "BASE" } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/get_accounts \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "family": "BASE" }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/get_accounts", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "family": "BASE" }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/get_accounts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "family": "BASE", }, ) print(response.status_code, response.json()) ``` ## get_delivery Read what the stream delivers beyond the watchlist: default keyword filters and Discord webhook, feed toggles, Binance Square accounts, news sources, callouts and the Instagram Discord destination. Tier read: the API key alone. The MCP tool of the same name needs the tweetstream:watchlist scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-get-delivery ### `POST /api/agent/actions/get_delivery` `https://tweetstream.io/api/agent/actions/get_delivery` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body #### Body example [Use the first complete copy of this example.](https://tweetstream.io/docs/api/agent-action-get-account#body) ### Response fields | Name | Type | Description | | --- | --- | --- | | `binanceSquare` | `object`, required | | | `binanceSquare.accounts` | `object[]`, required | | | `binanceSquare.accounts.account` | `string`, required | | | `binanceSquare.accounts.enabled` | `boolean`, required | | | `binanceSquare.accounts.name` | `string`, required | | | `binanceSquare.accounts.profileUrl` | `string`, required | | | `binanceSquare.canManage` | `boolean`, required | | | `callouts` | `object`, required | | | `callouts.callers` | `object[]`, required | | | `callouts.callers.callerId` | `string`, required | | | `callouts.callers.createdAt` | `string`, required | | | `callouts.callers.label` | `string`, required | | | `callouts.callers.platform` | `enum`, required | | | `callouts.callers.username` | `string`, required | | | `callouts.limit` | `number`, required | | | `callouts.pending` | `object[]`, required | | | `callouts.pending.createdAt` | `string`, required | | | `callouts.pending.input` | `string`, required | | | `callouts.pending.intentId` | `string`, required | | | `callouts.pending.label` | `string`, required | | | `callouts.pending.platform` | `enum`, required | | | `feeds` | `object`, required | | | `feeds.charity` | `object`, required | | | `feeds.charity.enabled` | `boolean`, required | | | `feeds.truthSocial` | `object`, required | | | `feeds.truthSocial.available` | `boolean`, required | | | `feeds.truthSocial.enabled` | `boolean`, required | | | `global` | `object`, required | | | `global.keywords` | `string[]`, required | | | `global.webhook` | `object`, required | Present when a Discord webhook is saved; endsWith is the last 4 characters of its URL. | | `global.webhook.configured` | `enum`, required | | | `global.webhook.endsWith` | `string`, required | | | `instagramDiscord` | `object`, required | | | `instagramDiscord.bot` | `object`, required | | | `instagramDiscord.bot.available` | `boolean`, required | | | `instagramDiscord.bot.delivering` | `boolean`, required | | | `instagramDiscord.bot.enabled` | `boolean`, required | | | `instagramDiscord.webhook` | `object`, required | | | `instagramDiscord.webhook.available` | `boolean`, required | | | `instagramDiscord.webhook.configured` | `boolean`, required | | | `instagramDiscord.webhook.enabled` | `boolean`, required | | | `newsSources` | `object[]`, required | | | `newsSources.available` | `boolean`, required | | | `newsSources.enabled` | `boolean`, required | | | `newsSources.id` | `string`, required | | | `newsSources.name` | `string`, required | | | `refusals` | `object[]`, required | | | `refusals.message` | `string`, required | | | `refusals.reason` | `enum`, required | | | `refusals.section` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "binanceSquare": { "accounts": [ { "account": "", "enabled": true, "name": "", "profileUrl": "" } ], "canManage": true }, "callouts": { "callers": [ { "callerId": "", "createdAt": "", "label": "", "platform": "pump_fun", "username": "" } ], "limit": 123.45, "pending": [ { "createdAt": "", "input": "", "intentId": "", "label": "", "platform": "pump_fun" } ] }, "feeds": { "charity": { "enabled": true }, "truthSocial": { "available": true, "enabled": true } }, "global": { "keywords": [ "" ], "webhook": { "configured": true, "endsWith": "" } }, "instagramDiscord": { "bot": { "available": true, "delivering": true, "enabled": true }, "webhook": { "available": true, "configured": true, "enabled": true } }, "newsSources": [ { "available": true, "enabled": true, "id": "", "name": "" } ], "refusals": [ { "message": "", "reason": "api_key_required", "section": "binanceSquare" } ] } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/get_delivery \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{}' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/get_delivery", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({}), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/get_delivery", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={}, ) print(response.status_code, response.json()) ``` ## manage_callouts Add or remove callout accounts, or cancel one still pending. Tier read: the API key alone. The MCP tool of the same name needs the tweetstream:watchlist scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-manage-callouts ### `POST /api/agent/actions/manage_callouts` `https://tweetstream.io/api/agent/actions/manage_callouts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `changes` | `object[]`, required | an array of at most 10 item(s) | | `changes.input` | `string`, required | a string that will be trimmed | | `changes.kind` | `enum`, required | | | `changes.label` | `string` | a string that will be trimmed | | `changes.platform` | `enum`, required | | #### Body example ```json { "changes": [ { "input": "marketdesk", "kind": "add", "label": "Market Desk", "platform": "pump_fun" } ] } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `results` | `object[]`, required | | | `results.kind` | `enum`, required | | | `results.outcome` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "results": [ { "kind": "add", "outcome": "applied" } ] } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/manage_callouts \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "changes": [ { "input": "marketdesk", "kind": "add", "label": "Market Desk", "platform": "pump_fun" } ] }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/manage_callouts", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "changes": [ { "input": "marketdesk", "kind": "add", "label": "Market Desk", "platform": "pump_fun" } ] }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/manage_callouts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "changes": [ { "input": "marketdesk", "kind": "add", "label": "Market Desk", "platform": "pump_fun", }, ], }, ) print(response.status_code, response.json()) ``` ## select_trial_accounts During a trial, pick which saved X accounts the trial streams. Tier read: the API key alone. The MCP tool of the same name needs the tweetstream:watchlist scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-select-trial-accounts ### `POST /api/agent/actions/select_trial_accounts` `https://tweetstream.io/api/agent/actions/select_trial_accounts` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `twitterUserIds` | `string[]`, required | The `twitterUserId`s (get_accounts, family BASE) the trial streams. | #### Body example ```json { "twitterUserIds": [ "1189745302" ] } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `outcome` | `enum`, required | | | `twitterUserIds` | `string[]`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "outcome": "applied", "twitterUserIds": [ "" ] } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/select_trial_accounts \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "twitterUserIds": [ "1189745302" ] }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/select_trial_accounts", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "twitterUserIds": [ "1189745302" ] }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/select_trial_accounts", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "twitterUserIds": [ "1189745302", ], }, ) print(response.status_code, response.json()) ``` ## set_delivery Change what the stream delivers: default and per-account keyword filters and Discord webhooks, event types, affiliate alerts, Binance Square, news sources, the Instagram Discord destination, and the Truth Social and charity feeds. Tier read: the API key alone. The MCP tool of the same name needs the tweetstream:watchlist scope. Canonical URL: https://tweetstream.io/docs/api/agent-action-set-delivery ### `POST /api/agent/actions/set_delivery` `https://tweetstream.io/api/agent/actions/set_delivery` ### Authorization | Name | Type | Description | | --- | --- | --- | | `Authorization` | `string`, required | Bearer authentication with your TweetStream API key: `Bearer `. | ### Body | Name | Type | Description | | --- | --- | --- | | `changes` | `object[]`, required | an array of at most 20 item(s) | | `changes.keywords` | `string[]`, required | Keyword filters; an empty list delivers every post. | | `changes.kind` | `enum`, required | | #### Body example ```json { "changes": [ { "keywords": [ "solana", "etf" ], "kind": "global_keywords" } ] } ``` ### Response fields | Name | Type | Description | | --- | --- | --- | | `results` | `object[]`, required | | | `results.kind` | `enum`, required | | | `results.outcome` | `enum`, required | | ### Responses | Status | Description | Headers | | --- | --- | --- | | `200` | Success | | | `400` | The input does not match the action's schema (INVALID_REQUEST) | | | `401` | Missing or invalid API key | | | `403` | The request carried a foreign Origin | | | `429` | Rate limit reached (RATE_LIMITED); retry after retryAfterSeconds | | | `503` | Temporarily unavailable; retry later | | #### 200 ```json { "results": [ { "kind": "global_keywords", "outcome": "applied" } ] } ``` #### 400 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 401 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 403 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 429 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) #### 503 [Use the first complete copy of this example.](https://tweetstream.io/docs/api/list-ultra-accounts#responses) ### Code samples #### cURL ```bash curl --request POST \ --url https://tweetstream.io/api/agent/actions/set_delivery \ --header "Authorization: Bearer $TWEETSTREAM_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "changes": [ { "keywords": [ "solana", "etf" ], "kind": "global_keywords" } ] }' ``` #### JavaScript ```javascript const response = await fetch("https://tweetstream.io/api/agent/actions/set_delivery", { method: "POST", headers: { Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "changes": [ { "keywords": [ "solana", "etf" ], "kind": "global_keywords" } ] }), }); console.log(response.status, await response.json()); ``` #### Python ```python import os import requests response = requests.post( "https://tweetstream.io/api/agent/actions/set_delivery", headers={"Authorization": f"Bearer {os.environ['TWEETSTREAM_API_KEY']}"}, json={ "changes": [ { "keywords": [ "solana", "etf", ], "kind": "global_keywords", }, ], }, ) print(response.status_code, response.json()) ```