explore searches, and xquik executes authenticated calls. Full account keys and OAuth tokens see 118 operations. Active guest paid_reads keys see exactly 33 eligible GET routes.
explore
Search the authenticated API catalog.explore makes no network calls and consumes no credits. Full credentials search 118 operations. Guest keys search only the 33 eligible GET routes.
Input:
Sandbox code
Pass
code as an async arrow function. It is required and can be up to
10,000 characters.Spec access
The function runs against
spec.endpoints so agents can filter endpoint
paths, parameters, categories, costs, and response shapes before making a
live call.Find all free endpoints
Find endpoints by category
Search by keyword
xquik
Execute API calls allowed by the authenticated credential. Full account keys and OAuth tokens keep their existing account capabilities. Guest keys can execute only the 33 eligible GET reads. Auth is injected automatically. Input:Sandbox code
Pass
code as an async arrow function. It is required and can be up to
10,000 characters.Authenticated calls
The function can call
xquik.request(path, { method, body, query }) with
auth injected automatically.xquik.request() sends the normalized contract automatically. Responses use snake_case fields, date-time fields as Unix seconds, and structured error objects. A default REST createdAt field becomes created, while fields such as publishedAt become published_at.
List and search responses use has_more and next_cursor, even when a REST page shows has_next_page or hasMore. Pass next_cursor back as the cursor query parameter for most X data pages. Use after for /api/v1/draws, /api/v1/extractions, /api/v1/events, and /api/v1/radar. Use afterCursor for /api/v1/drafts.
Continue through empty filtered pages while has_more is true and the cursor advances. Stop when you reach the requested total or has_more becomes false. Treat a missing or repeated next_cursor while has_more is true as stalled pagination and return the partial count plus a clear stop reason.
Errors use error.type, error.code, and error.message, with fields such as error.retryable or error.retry_after when available. Dependency failures use HTTP 424 in this contract. Fix validation errors before retrying, and respect retry_after on 429.
Write and media responses also use the MCP-normalized snake_case contract. Read tweet_id, write_action_id, charged_credits, media_id, media_url, and message_id from xquik.request() results. REST and generated SDK pages may show camelCase fields such as tweetId, writeActionId, chargedCredits, mediaId, and messageId; keep MCP agents on snake_case when reading tool results.
Tool output is limited to 24,000 characters. If a result includes [TRUNCATED], request fewer rows, project only needed fields, or aggregate inside the sandbox. Use REST, SDKs, or extraction exports when a workflow must persist every full row.
Scope and unavailable operations
The REST contract documents 126 operations. A full account key or OAuth token exposes 118 and omits 8 credential or session-bound operations:- Create, list, or revoke account API keys
- Charge a saved payment method through quick top-up
- Open the session-based account top-up redirect route
- Create, poll, or top up a guest wallet
/api/v1/guest-wallets, /api/v1/guest-wallets/topups, or /api/v1/guest-wallets/status through xquik.request(). Follow the accountless guest wallet guide outside MCP.
A guest paid_reads key receives a separate 33-operation catalog. Every entry is an eligible paid-read GET route. The sandbox cannot execute mutations or noneligible routes.
A 402 creates no checkout. Report its payment_options, ask the user to choose an amount and option, then wait for explicit confirmation. Full account MCP sessions may call only an advertised account checkout action present in their catalog. Guest wallet creation and top-up remain direct REST after confirmation.
Workflow Examples:
Compose an algorithm-optimized tweet (3-step, free)
Save a writing style from screenshots (free)
Browse trending news from radar (free)
Radar + Style + Compose combined (free)
Analyze a user’s writing style
Summarize up to 100 tweets with guarded pagination (credits required)Use
q for keywords and X search operators, or pass a plain Tweet ID or X
status URL when the agent receives a single stored link.
Summarize up to 100 followers with guarded pagination (credits required)
Scrape tweet replies to CSV, JSON, or XLSX (credits required)
Post a tweet or reply with public media URLs (credits required)
Upload media for a DM (credits required)
message_id with the uploaded media_id. Keep full DM bodies out of
shared MCP outputs; return IDs, status, media references, and source filenames
instead. Leave reply_to_message_id unset because the DM send endpoint rejects
reply threading.
Download media and get gallery link (credits required)
Bulk download: search + download combined
Monitor a user + create webhook (monitor creation requires credits, webhook is free)
Poll stored monitor events (free)
Run an extraction with a resumable handoff (credits required)
Agent handoff patterns
MCP returns JSON. Use extraction export endpoints when you need Xquik to generate CSV, JSON, XLSX, Markdown, or PDF files. For agent queues, CRMs, and warehouses, return a small object with the original job, the route used, normalized rows or IDs to store, and the next cursor or write action to poll. Avoid returning rawtweets or users pages when the next agent or worker
needs durable handoff rows.
Search tweets to JSON
Call
GET /api/v1/x/tweets/search with keywords, operators, a Tweet ID, or an X status URL in q. Store tweets[].id, tweets[].text, tweets[].author, tweets[].created, has_more, next_cursor, and the original q. Cost: 1 credit per tweet returned.Scrape tweet replies to files
Call
POST /api/v1/extractions/estimate, then POST /api/v1/extractions with reply_extractor and targetTweetId. Poll GET /api/v1/extractions/{id}, export CSV/JSON/XLSX with GET /api/v1/extractions/{id}/export, and store reply rows plus has_more and next_cursor. Cost: 1 credit per reply extracted or returned.Export followers to CRM
Call
GET /api/v1/x/users/{id}/followers or POST /api/v1/extractions with follower_explorer. Store users[].id, users[].username, users[].name, users[].followers, has_more, and next_cursor. Cost: 1 credit per follower returned or extracted.Post media tweets or replies
Call
POST /api/v1/x/tweets with media: ["https://..."]. Store tweet_id or write_action_id, reply_to_tweet_id, account, charged_credits, and the original media URLs. Cost: 30 credits text-only, plus 2 credits per started MB across attached media.Send DMs with media
Call
POST /api/v1/x/media, then POST /api/v1/x/dm/{userId} with one media_ids value. Store media_id, media_url, message_id, user_id, account, and source URL or filename. Keep full DM bodies out of shared outputs and leave reply_to_message_id unset. Cost: 10 credits per media upload plus 10 credits per DM send.Track tweet or reply writes
Call
POST /api/v1/x/tweets, then GET /api/v1/x/write-actions/{id} when pending. Store tweet_id, reply_to_tweet_id, write_action_id, status, charged, charged_credits, and media. Cost: 30 credits text-only, plus 2 credits per started MB across attached media.Monitor tweets to webhooks
Call
POST /api/v1/monitors or POST /api/v1/monitors/keywords, then POST /api/v1/webhooks. Store monitor.id, event_types, next_billing_at, webhook.id, webhook URL, and the one-time webhook.secret; run POST /api/v1/webhooks/{id}/test before routing production events. Verify X-Xquik-Signature, de-dupe production payloads with deliveryId and streamEventId, and inspect GET /api/v1/webhooks/{id}/deliveries for retry status rows. Each payload contains one monitor event, so process multiple POSTs when one check catches multiple new matching tweets. Cost: 21 credits per active monitor-hour; webhook delivery is included.Replay monitor events
Call
GET /api/v1/events when a receiver missed webhook delivery or a downstream queue needs replay. Store event_id, type, monitor_id, monitor_type, occurred_at, has_more, and next_cursor; use after for the next page. Do not use cursor on event pages.POST /api/v1/x/tweets rejects media_ids with 400 unsupported_field; pass up to 4 public image URLs or exactly 1 public MP4 video URL up to 100 MB in media instead. Reserve uploaded media_id values for direct messages.
Look up known tweet IDs
GET /api/v1/x/tweets is available in both the full and paid_reads catalogs. Send at most 100 tweet IDs.
Subscribe (free, returns checkout or billing portal URL)Run this mutation only after the user explicitly asks to subscribe or open billing.
API endpoints
The REST API documents 126 operations. The full MCP catalog exposes 118 across 10 categories:Account, composition, and credits
20 MCP operations across
account, composition, and credits: account info, subscribe, X identity, compose, styles, drafts, radar, balance checks, checkout creation, and checkout status.Extractions and media
10 operations across
extraction and media: giveaway draws, extraction jobs, estimates, exports, and media download.Monitoring and webhooks
19 operations in
monitoring: account monitors, keyword monitors, stored events, webhooks, deliveries, and test delivery.Support
5 operations in
support: create, list, read, reply to, and close support tickets.X data reads
38 operations in
twitter: batch and single tweet lookup, tweet search, article lookup, user lookup, follow checks, trends, bookmarks, notifications, timeline, DM history, likes, media, followers, replies, communities, and lists.X accounts and writes
25 operations across
x-accounts and x-write: connect accounts, retry connection issues, post tweets, like, retweet, follow, remove followers, send DMs, upload media, update profiles, and manage community membership.explore to browse the 118-operation MCP catalog with parameters and response shapes.
With a guest paid_reads key, explore and xquik expose exactly 33 twitter GET operations. Use the guest paid-read route inventory as the public route list.
Cost summary
Always free discovery
explore is free. Use it to find endpoints, parameters, and response shapes before making API calls.Free account and stored records
Compose, cached styles, drafts, radar, subscribe, account, support, credits, X account management, webhooks, stored monitors, stored events, and existing extraction or draw reads are free.
Metered reads and jobs
Tweet search, user lookup, follow checks, media download, trends, extraction creation, and draw creation are metered.
Monitor billing
Active instant monitors cost 21 credits per active monitor-hour. Creating monitors requires enough available credits.
Write actions
Tweet, reply, like, retweet, follow, DM, profile, community, and media upload writes are metered.
Metered refreshes
Fresh style analysis after the 7-day cache window requires enough available credits.
Error handling
- 402 /
no_subscription/subscription_inactive: Report the billing state and available account actions. Existing available credits can still fund metered calls. Ask the user to choose and confirm before callingPOST /api/v1/subscribe. - 402 /
no_credits/insufficient_credits: Reportpayment_options. Full account sessions may create account checkout after confirmation. Guest sessions may explain the direct REST top-up flow, but MCP cannot execute it. - 429 /
rate_limit_exceeded: Respecterror.retry_after, then retry safe reads with backoff. - 424 dependency errors: Report
error.code, preserve partial aggregates, and retry only whenerror.retryableallows it. - Validation errors: Fix the path, query, or body before retrying.