Skip to main content
Xquik API MCP v2.5.4 exposes a credential-scoped catalog through 2 tools: 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.
Sandbox API:
Examples:
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.
Sandbox API:
Response contract: 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
The guest wallet routes are direct REST only. Never call /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)
Store 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 raw tweets 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.
Do not upload media before posting tweets or replies when the media is already public. 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.
Use 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.
Never combine free and paid endpoints in a single Promise.all. A 402 error on one call kills all results. Call free endpoints first, then paid ones separately.

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 calling POST /api/v1/subscribe.
  • 402 / no_credits / insufficient_credits: Report payment_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: Respect error.retry_after, then retry safe reads with backoff.
  • 424 dependency errors: Report error.code, preserve partial aggregates, and retry only when error.retryable allows it.
  • Validation errors: Fix the path, query, or body before retrying.
The MCP server never starts subscriptions, checkout, top-up, or other billing mutations in response to an API error. Guest credential routes are never executable through MCP.
Last modified on July 16, 2026