twitterapiio). Neither needs an X developer account.
Get a key at https://app.twittrapi.com/api-key. A new account gets $0.50 of test credit, valid 7 days, no card needed. The plugin sends the key in the X-API-KEY header and asks for the compact format=simple JSON on every read.
Things worth knowing:
- Reads are billed per call (about $0.0001 each; a page of ~20 tweets is one call).
balance.getand everymonitors.*call are free. - IDs are numeric strings. Tweet IDs are the number at the end of the tweet URL. The user operations that take
userIdalso takeuserId: "-1"withusernameto work by handle;users.resolveIdsturns up to 100 handles into IDs in one call. - Paging: pass a page’s
nextCursorascursor. X decides the page size, socountis a hint. - Account monitoring needs a plan booked in the TwittrAPI dashboard under Monitors (one account on the 60-second class is free). Without a plan,
monitors.addAccountsanswers 402. - Webhooks: each webhook has its own
whsec_secret, returned bymonitors.createWebhook(and bymonitors.updateWebhookwithrotateSecret). Store it as the integration’s webhook secret; deliveries are verified with HMAC-SHA256 over<t>.<raw body>and rejected outside a 5-minute window. Put the webhook’s ID in the account’swebhook_idso deliveries reach the right tenant: every delivery names it inX-TwittrAPI-Webhook. - Deliveries are at least once. A failed delivery (no 2xx within 5 seconds) is retried with the same event ID, with backoff up to 2 hours, for 24 hours; a retry can rarely arrive twice. The plugin stores events by ID, so a repeat stores nothing new, but each delivery is logged as an event and reaches your
webhookHooks: dedupe on the event’sidif a hook must run once. - A webhook is turned off after 20 failed deliveries in a row (
active: falsewithdisabledReason). Fix the endpoint, sendmonitors.updateWebhookwithactive: true, and read what was missed withmonitors.getEvents(events are kept 7 days).
- 42 typed API operations
- 10 synced entities (
communities,friendships,lists,monitoredAccounts,monitorEvents,monitorWebhooks, and 4 more) for fast.search()/.list() - 2 incoming webhook event types
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the TwittrAPI API key before the first call: More: API Key
pnpm corsair setup --plugin=twittrapi --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Search tweets from an accountQuery synced data
Synced entities supporttenant.twittrapi.db.<entity>.search() and .list(): communities, friendships, lists, monitoredAccounts, monitorEvents, monitorWebhooks, trendLocations, trends, tweets, users.
See Database for filters and operators.
Webhooks
This plugin registers 2 webhook event types. Configure the provider to POST to your Corsair HTTP handler, then usewebhookHooks on the plugin factory.
See Webhooks for every event path and payload shape, and Webhooks concept for routing.
What’s next
API reference
Every
twittrapi.api.* operation with input and output types.Database
Synced entities, search filters, and operators.
Webhooks
Event paths, payloads, and
webhookHooks examples.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.