docs, search, execute, and whoami. Native mode exposes docs, readSavedResult, whoami, and one tool for each eligible OpenAPI operation. Active guest paid_reads keys see only the eligible paid-read routes in either mode.
Modern clients negotiate MCP 2026-07-28 through server/discover. Current SDKs add required request metadata and headers.
See MCP 2026-07-28.
Native OpenAPI tools
Connect tohttps://xquik.com/mcp?codemode=false for ordinary MCP tools. Full
credentials get docs, readSavedResult, and 1 tool for each eligible
operation. Guest keys get docs, readSavedResult, and 1 tool for each
eligible GET route.
Native names, schemas, and contracts come from OpenAPI. compose and
estimateExtraction are read-only. Clients read each JSON Schema from
tools/list. The server embeds no model prompt, routing, sample count, or endpoint preference.
Use https://xquik.com/mcp for Code Mode. Choose native mode for one tool per operation. Binary downloads, credential lifecycle, checkout, top-up and subscription operations remain REST-only.docs
Search canonical public documentation. docs is read-only and uses no credits.
Input. Pass a non-empty query string of up to 500 characters.
Output. structuredContent.results lists each matching passage with its id, url, title, and text. The text content shows the same passages as <result> blocks within 24,000 characters.whoami
Return the signed-in account’s stable id. whoami takes no arguments, makes no API request, and uses no credits.
Output. { "id": "user:<id>" }. The id stays the same across token refresh, reconnection, and permission changes. It never moves to another account. Use it to tell connected accounts apart. ChatGPT reads it as the app’s profile tool.readSavedResult
Native mode reads a saved oversized answer in pages. Pages make no API requests and use no credits.
Input. Pass result_id from the oversized answer and optional offset, which starts at 0.
Output. Each page returns characters, next_offset, and text within 24,000 characters.
Pass next_offset as offset until it is null, then join each text in order.
A page never splits a character.search
Search the authenticated API catalog. search makes no network calls and uses no credits. Full credentials search every catalog route. Guest keys search the eligible paid-read routes.
Input.
Pass required code as an async arrow function of up to 10,000 characters.
Read spec.paths. Return matching paths, methods, and relevant contract fields.
Inspect inputs and response fields separately when an operation is large.
Sandbox API.
Inputs resolve inline. Response $ref values point into spec.components.schemas.
The catalog includes only response schemas reachable from your allowed operations.
Search retains operation-specific response descriptions. Date-only fields keep string types.
Follow references to inspect shared fields and recursive types.Inspect an operation’s input contract
search call.
For example, #/components/schemas/PaginatedTweets identifies the shared pagination schema.execute
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 eligible GET reads. The server injects authentication and required idempotency headers.
For full credentials, execute carries destructiveHint: true and openWorldHint: true. As a result, MCP clients such as Claude ask before each call. Guest keys see it as read-only. Native tools carry the hints of their operation, so reads run without a prompt.
Input.
Pass code as an async arrow function of up to 10,000 characters. xquik is global and the function’s first argument.
Pass optional result_id to load a saved result into xquik.result.
Without it, xquik.result is null.
Pass the function itself, not a promise or its result.
Place API calls inside its body. Non-functions fail before any API request starts.
path works with or without the /api/v1 prefix, as in /x/users/nasa/follow.
Sandbox API.xquik.request() returns success, status, result, errors, and messages.
status contains the HTTP status. result contains the endpoint body.
A rejected request includes error.status when available. Existing string-path
calls still return the body for compatibility. Hosted MCP injects a unique
Idempotency-Key and reuses it for bounded transient retries. Verify unresolved
writes. Retry only when safe_to_retry is true. Results use snake_case with Unix
timestamps. CamelCase reads work, including favoriteCount for like_count. Errors stay structured. Pagination uses has_more and next_cursor.
Compact extraction results retain like_count, retweet_count, reply_count, quote_count, view_count, and bookmark_count. They omit profile images and nested enrichment.
MCP keeps every safe field that X supplies. Optional fields stay absent. See Read Data Richness for the REST field map.
Missing response-field reads return undefined and produce warnings.
Each warning maps a missing field to available response keys.
Optional-field fallbacks remain valid. Warnings contain field names, never response values.
With warnings, text and structured output both contain { result, warnings }.
The combined output follows the existing 24,000-character limit.
List and search responses use has_more and next_cursor. They do so even when REST shows has_next_page or hasMore. Pass next_cursor unchanged as cursor for X reads, draws, extractions, and events. Never replace an extraction cursor with offset. Use after for /api/v1/radar and afterCursor for drafts.
Hosted MCP keeps each requested limit. REST enforces documented bounds.
Omit mode for tweet search, replies, followers, following, and verified
followers. Those operations use automatic maximum coverage. Pass
next_cursor back unchanged. Use mode=standard only for legacy pagination.
Keep paging while has_more is true and the cursor advances. That includes empty pages, filtered or not. 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. Return the partial count plus a stop reason.
For advanced nested-reply diagnostics, call
/api/v1/x/tweets/<tweet_id>/replies?mode=complete&limit=25000.
Complete mode adds nested replies & a coverage diagnostic. Direct replies match
inReplyToId. Keep nested_replies separate.
Trust diagnostic.complete. HTTP 424 replies_incomplete keeps rows.
MCP returns that documented body instead of a tool error.
Inspect coveragePercentage, recommendedFallback, and X-dependent coverage
limits.
Errors use error.type, error.code, and error.message. They add fields such as error.retryable or error.retry_after when available. Invalid routes stay blocked without suggesting or calling a different operation. Find the exact method and path in spec.paths before retrying. Dependency failures use HTTP 424 in this contract. Fix validation errors before retrying. Respect retry_after on 429.
Write and media results follow the same contract. Read tweet_id, write_action_id, charged_credits, media_id, media_url, and message_id from response.result.
Both search and execute return compact JSON within 24,000 characters. Whitespace inside strings stays unchanged. Native API tools apply the same limit to successful & failed responses.
The limit bounds tool output, not catalog access or available results. Large schema selections can exceed it. Oversized output returns a shortened copy, never an error. result stays valid JSON. Lists keep whole items from the start. Each cut says --- TRUNCATED ---. Examples are --- TRUNCATED --- 11 more items and --- TRUNCATED --- 5,000 chars. A truncated object sits beside result. Its characters gives the whole answer’s size. Its next says what to do for the rest. A saved answer adds result_id & download_url. That link downloads the whole result as a CSV file. An answer too large to keep returns characters, next & any saved reads. An ordinary result containing an error field is not a tool failure.
Output errors do not undo completed API actions or charges.
Use REST, SDKs, or extraction exports to store every row.Cursor pages and response size
Cursor-based reads may return fewer rows than requested to fit each MCP response. Continue withnext_cursor while has_more is true.
Deferred rows remain available through that cursor, with their fields intact.
Only rows delivered in each page incur result charges.
Each API response within execute must fit within 2 MiB.
A single larger row returns HTTP 413 response_item_too_large before result billing.
Retrieve that row through REST.
Projecting fields in execute cannot reduce the incoming API response size.
The separate 24,000-character tool output limit still applies.Recover oversized results
When saving succeeds, thetruncated object of an oversized API result includes result_id & download_url.
Its next names only tools your catalog lists. Use 1 of these retrieval methods.- In Code Mode, pass
result_idtoexecute, then project or pagexquik.result. - In native mode, pass
result_idwithoffset0 toreadSavedResult, then eachnext_offset. - Open
download_urlsigned in to the same account. It downloads the whole result as a CSV file. - Read
xquik://results/{result_id}through MCPresources/read.
{ result, warnings? } JSON.
Return selected fields, fewer rows, shorter strings, or an aggregate from saved data.
Reading saved data makes no API requests and spends no extraction credits.
Explicit xquik.request() calls still follow normal billing.
Use the original account and credential scope.
Another account or scope cannot retrieve the result.
Missing or unavailable results return an error.result_id.
Every API answer MCP accepts fits in storage. A storage failure may still prevent saving.
An oversized search answer is not saved. Return a smaller selection for the rest.
Without a saved result, contact support before repeating requests that cost credits.
Verify completed writes before retrying them.Scope and unavailable operations
The MCP operation boundary lists excluded operations. Guest wallet credential routes and file downloads use REST. Guest keys expose only eligible paid-read routes. A402 creates no checkout. Its MCP answer keeps error, message, balance, and required. It also keeps credits_renew_at when a plan renews, and dashboard as a full link. It leaves out payment_options, next_step and the top-up fields. Report the balance and send the user to the dashboard link to add credits.
Examples.
Each page holds complete execute calls.Agent handoff patterns
Use extraction exports for generated files. Keep agent handoffs small. Include the job, route, stored row IDs, next cursor, and poll action. Avoid raw pages when later workers need durable rows.Search tweets to JSON
Call
GET /api/v1/x/tweets/search. Put keywords, operators, a Tweet ID, or an X status URL in q. Valid time bounds apply to every page. The start is inclusive and the end is exclusive. Store tweets[].id, tweets[].text, tweets[].author, tweets[].created, has_more, next_cursor, and the original q. The cost is 1 credit per tweet returned.Scrape tweet replies to files
Call
POST /api/v1/extractions with reply_extractor and targetTweetId. The create route handles required preflight. Poll GET /api/v1/extractions/{id}. Export CSV, JSON, or XLSX with GET /api/v1/extractions/{id}/export. Store reply rows plus has_more and next_cursor. The cost is 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. The cost is 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. The cost is 30 credits text-only. Add 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. The cost is 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. The cost is 30 credits text-only. Add 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. Deduplicate production payloads with deliveryId and streamEventId. Inspect GET /api/v1/webhooks/{id}/deliveries for retry status rows. Each payload contains one monitor event. Process multiple POSTs when one check catches multiple new matching tweets. The cost is 30 credits per active monitor-hour. The rate includes webhook delivery.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 cursor for the next page.media. Send up to 4 image URLs or exactly 1 MP4 video URL. The video can be up to 100 MB. For a local file, upload it and pass its media_id in media_ids. Never send media and media_ids together.Look up known tweet IDs
GET /api/v1/x/tweets is available in both the full and paid_reads catalogs. Send as many tweet IDs as fit in 1 URL.API endpoints
The full MCP catalog groups its operations into 10 categories.Account, composition, and credits
MCP operations across
account, composition, and credits cover account info and X identity. They also cover compose, styles, drafts, radar, and balance checks.Extractions and media
Operations across
extraction and media cover giveaway draws, extraction jobs, estimates, and media download.Monitoring and webhooks
Operations in
monitoring cover account monitors, keyword monitors, and post monitors. They also cover stored events, webhooks, deliveries, and test delivery.Support
Operations in
support create, list, read, reply to, and close tickets.Tweets, profiles & followers
Operations in
twitter cover batch and single tweet lookup, tweet search, and article lookup. The category also covers user Article lists, hidden replies, user lookup, and repost checks. It covers follower and following ID lists, creator subscriptions, affiliates, and follow checks. It covers trends, bookmarks, notifications, timeline, DM history, likes, media, and highlights. It also covers followers, replies, communities, lists, and job listings. Timeline and thread results exclude X ads.X accounts and writes
Operations across
x-accounts and x-write connect accounts and resolve challenges. They post tweets, like, retweet, follow, and remove followers. They also send and delete DMs, upload media, update profiles, and manage communities.paid_reads key limits search and execute to the eligible twitter GET operations. The docs tool remains available. Use the guest paid-read route inventory as the public route list.Cost summary
Always unmetered discovery
docs and search cost no credits. They return documentation and API contract details.Unmetered account and stored records
Compose, cached styles, drafts, radar, account, and support cost no credits. The same goes for credits, X account management, webhooks, and stored monitors. Stored events and existing extraction or draw reads cost no credits either.
Metered reads and jobs
Tweet search, user lookup, follow checks, media download, and trends are metered. Extraction creation and draw creation are metered too.
Monitor billing
Active monitors cost 30 credits per monitor-hour. Creating one requires enough available credits.
Write actions
Tweet, reply, like, retweet, follow, DM, profile, community, and media upload writes are metered. A write that must sign in to your X account first adds 10 credits. Xquik refunds them if the sign-in fails. See the X sign-in fee.
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. Existing available credits can still fund metered calls. Send the user to thedashboardlink to choose a plan. - 402 /
no_credits/insufficient_credits. Reportbalanceandrequired. Then send the user to thedashboardlink to add credits. 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, keep partial aggregates, and retry only whenerror.retryableallows it. - Validation errors. Fix the path, query, or body before retrying.
execute throws a failed request as an Error. A native tool answers it as an error result with the same text. The text names the method, path, and HTTP status of the failed request. The API’s JSON error follows.