Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xquik.com/llms.txt

Use this file to discover all available pages before exploring further.

The Xquik MCP server exposes 2 tools: explore (search the API spec) and xquik (execute API calls). Connect to https://xquik.com/mcp with x-api-key or OAuth 2.1 Bearer auth. API keys fit terminal clients; OAuth fits browser MCP clients.

​
explore

Search the API endpoint catalog. Read-only, no network calls, and no credits required. The call still requires MCP authentication through an API key or OAuth Bearer token. Use this to discover available endpoints, check parameters, and find the right API path before executing calls. 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: 
interface EndpointInfo {
  method: string;
  path: string;
  summary: string;
  category: string; // account, composition, credits, extraction, media, monitoring, support, twitter, x-accounts, x-write
  free: boolean;
  parameters?: Array<{
    name: string;
    in: 'query' | 'path' | 'body';
    required: boolean;
    type: string;
    description: string;
  }>;
  responseShape?: string;
}

declare const spec: { endpoints: EndpointInfo[] };
Examples:
Find all free endpoints 
async () => {
  return spec.endpoints.filter(e => e.free);
}
Find endpoints by category 
async () => {
  return spec.endpoints.filter(e => e.category === 'composition');
}
Search by keyword 
async () => {
  return spec.endpoints.filter(e => e.summary.toLowerCase().includes('tweet'));
}

​
xquik

Execute API calls against your Xquik account. The agent writes code using xquik.request() with auth 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: 
declare const xquik: {
  request(path: string, options?: {
    method?: string;  // default: 'GET'
    body?: unknown;
    query?: Record<string, string>;
  }): Promise<unknown>;
};
declare const spec: { endpoints: EndpointInfo[] };
Response contract: xquik.request() uses the normalized v1 contract automatically. List and search responses use has_more and next_cursor, even when the REST API page shows the default has_next_page field. Pass next_cursor back as the cursor query parameter for most X data pages. Use after instead for /api/v1/draws, /api/v1/extractions, /api/v1/events, and /api/v1/radar. 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. Workflow Examples:
Compose an algorithm-optimized tweet (3-step, free) 
async () => {
  // Step 1: Get algorithm data and follow-up questions
  const compose = await xquik.request('/api/v1/compose', {
    method: 'POST',
    body: { step: 'compose', topic: 'AI agents' }
  });
  return compose;
  // Returns contentRules, followUpQuestions, scorerWeights
  // Step 2: After user answers: { step: 'refine', goal, tone, topic }
  // Step 3: After drafting: { step: 'score', draft }
  // The score step runs algorithm checks. The draft must pass
  // all checks before presenting to the user.
}
Save a writing style from screenshots (free) 
async () => {
  // When a user shares tweet screenshots, extract the texts and save as a style.
  // This lets free users clone any writing voice without a subscription.
  return xquik.request('/api/v1/styles/elonmusk', {
    method: 'PUT',
    body: {
      label: 'Elon Musk style',
      tweets: [
        { text: 'The most entertaining outcome is the most likely' },
        { text: 'Mars, here we come!!' }
      ]
    }
  });
  // Then compose with: POST /api/v1/compose { step: 'compose', topic: '...', styleUsername: 'elonmusk' }
}
Browse trending news from radar (free) 
async () => {
  return xquik.request('/api/v1/radar');
}
Radar + Style + Compose combined (free) 
async () => {
  const [radar, styles] = await Promise.all([
    xquik.request('/api/v1/radar'),
    xquik.request('/api/v1/styles'),
  ]);
  return { radar, styles };
}
Analyze a user’s writing style 
async () => {
  // Returns cached style if available (free)
  // Auto-refreshes from X if cache older than 7 days (subscription required)
  return xquik.request('/api/v1/styles', {
    method: 'POST',
    body: { username: 'elonmusk' }
  });
}
Search tweets with cursor pagination (subscription required) 
async () => {
  const query = 'from:xquikcom giveaway';
  const rows = [];
  let cursor;
  let hasMore = false;
  let nextCursor = '';

  for (let pageNumber = 0; pageNumber < 2; pageNumber += 1) {
    const page = await xquik.request('/api/v1/x/tweets/search', {
      query: {
        q: query,
        ...(cursor ? { cursor } : {})
      }
    });

    rows.push(...page.tweets.map(tweet => ({
      source: 'xquik_mcp',
      job: 'tweet_search',
      query,
      tweet_id: tweet.id,
      text: tweet.text,
      author_id: tweet.author?.id ?? null,
      author_username: tweet.author?.username ?? null,
      created: tweet['created'] ?? null,
      url: tweet.url ?? null,
      like_count: tweet.like_count ?? null,
      reply_count: tweet.reply_count ?? null,
      retweet_count: tweet.retweet_count ?? null
    })));
    hasMore = Boolean(page.has_more);
    nextCursor = page.next_cursor ?? '';
    if (!hasMore || nextCursor === '') break;
    cursor = nextCursor;
  }

  return {
    source: 'xquik_mcp',
    job: 'tweet_search',
    rows,
    has_more: hasMore,
    next_cursor: nextCursor
  };
}
List follower pages (subscription required) 
async () => {
  const sourceUser = 'xquikcom';
  const rows = [];
  let cursor;
  let hasMore = false;
  let nextCursor = '';

  for (let pageNumber = 0; pageNumber < 2; pageNumber += 1) {
    const page = await xquik.request(`/api/v1/x/users/${sourceUser}/followers`, {
      query: {
        pageSize: '50',
        ...(cursor ? { cursor } : {})
      }
    });

    rows.push(...page.users.map(user => ({
      source: 'xquik_mcp',
      job: 'follower_export',
      source_user: sourceUser,
      user_id: user.id,
      username: user.username,
      name: user.name ?? null,
      followers: user.followers ?? null,
      following: user.following ?? null,
      verified: user.verified ?? null,
      profile_picture: user.profile_picture ?? null,
      page_index: pageNumber
    })));
    hasMore = Boolean(page.has_more);
    nextCursor = page.next_cursor ?? '';
    if (!hasMore || nextCursor === '') break;
    cursor = nextCursor;
  }

  return {
    source: 'xquik_mcp',
    job: 'follower_export',
    source_user: sourceUser,
    rows,
    has_more: hasMore,
    next_cursor: nextCursor
  };
}
Scrape tweet replies to CSV, JSON, or XLSX (subscription required) 
async () => {
  const body = {
    toolType: 'reply_extractor',
    targetTweetId: '1893704267862470862',
    resultsLimit: 500
  };

  const estimate = await xquik.request('/api/v1/extractions/estimate', {
    method: 'POST',
    body
  });

  if (estimate.allowed === false) {
    return {
      source: 'xquik_mcp',
      job: 'reply_extraction',
      status: 'blocked',
      error: estimate.error,
      credits_required: estimate.credits_required,
      credits_available: estimate.credits_available
    };
  }

  const extraction = await xquik.request('/api/v1/extractions', {
    method: 'POST',
    body
  });

  return {
    source: 'xquik_mcp',
    job: 'reply_extraction',
    extraction_id: extraction.id,
    status: extraction.status,
    target_tweet_id: body.targetTweetId,
    results_limit: body.resultsLimit,
    estimated_results: estimate.estimated_results,
    credits_required: estimate.credits_required,
    poll: `/api/v1/extractions/${extraction.id}`,
    export_csv: `/api/v1/extractions/${extraction.id}/export?format=csv`,
    export_json: `/api/v1/extractions/${extraction.id}/export?format=json`,
    export_xlsx: `/api/v1/extractions/${extraction.id}/export?format=xlsx`
  };
}
Post a tweet or reply with public media URLs (subscription required) 
async () => {
  const body = {
    account: 'myxhandle',
    text: 'Launch media is ready',
    reply_to_tweet_id: '1893456789012345678',
    media: ['https://example.com/product-demo.mp4']
  };

  const result = await xquik.request('/api/v1/x/tweets', {
    method: 'POST',
    body
  });

  if (result.error === 'x_write_unconfirmed') {
    return {
      source: 'xquik_mcp',
      job: 'tweet_write',
      status: result.status,
      write_action_id: result.write_action_id,
      charged: result.charged,
      retryable: result.retryable,
      poll: `/api/v1/x/write-actions/${result.write_action_id}`,
      account: body.account,
      reply_to_tweet_id: body.reply_to_tweet_id,
      media: body.media
    };
  }

  return {
    source: 'xquik_mcp',
    job: 'tweet_write',
    status: 'posted',
    tweet_id: result.tweet_id,
    account: body.account,
    reply_to_tweet_id: body.reply_to_tweet_id,
    media: body.media,
    charged: true
  };
}
Upload media for a DM (subscription required) 
async () => {
  const account = 'myxhandle';
  const user_id = '44196397';
  const source_url = 'https://example.com/image.png';

  const media = await xquik.request('/api/v1/x/media', {
    method: 'POST',
    body: {
      account,
      url: source_url
    }
  });

  const dm = await xquik.request(`/api/v1/x/dm/${user_id}`, {
    method: 'POST',
    body: {
      account,
      text: 'Here is the asset',
      media_ids: [media.media_id]
    }
  });

  return {
    source: 'xquik_mcp',
    job: 'dm_media',
    status: 'sent',
    user_id,
    account,
    source_url,
    media_id: media.media_id,
    media_url: media.media_url,
    message_id: dm.message_id
  };
}
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 (subscription required) 
async () => {
  const tweet_input = '1234567890';
  const download = await xquik.request('/api/v1/x/media/download', {
    method: 'POST',
    body: { tweetInput: tweet_input }
  });

  return {
    source: 'xquik_mcp',
    job: 'media_download',
    mode: 'single',
    tweet_input,
    tweet_id: download.tweet_id,
    gallery_url: download.gallery_url,
    cache_hit: download.cache_hit,
    note: 'Store gallery_url as the saved media gallery. It is not an uploaded media_id for DMs.'
  };
}
Bulk download: search + download combined 
async () => {
  const query = 'from:berktavsan has:videos';
  const search = await xquik.request('/api/v1/x/tweets/search', {
    query: { q: query }
  });
  if (!search.tweets?.length) {
    return {
      source: 'xquik_mcp',
      job: 'bulk_media_download',
      status: 'empty',
      query
    };
  }

  const tweetIds = search.tweets.map(t => t.id).slice(0, 50);
  const download = await xquik.request('/api/v1/x/media/download', {
    method: 'POST',
    body: { tweetIds }
  });

  return {
    source: 'xquik_mcp',
    job: 'bulk_media_download',
    status: 'ready',
    query,
    tweet_ids: tweetIds,
    gallery_url: download.gallery_url,
    total_tweets: download.total_tweets,
    total_media: download.total_media
  };
}
Monitor a user + create webhook (monitor creation requires subscription, webhook is free) 
async () => {
  const monitor = await xquik.request('/api/v1/monitors', {
    method: 'POST',
    body: { username: 'elonmusk', eventTypes: ['tweet.new', 'tweet.reply'] }
  });
  const webhook = await xquik.request('/api/v1/webhooks', {
    method: 'POST',
    body: { url: 'https://example.com/hook', eventTypes: ['tweet.new', 'tweet.reply'] }
  });
  const test = await xquik.request(`/api/v1/webhooks/${webhook.id}/test`, {
    method: 'POST'
  });
  return {
    monitor_id: monitor.id,
    event_types: monitor.event_types,
    next_billing_at: monitor.next_billing_at,
    webhook_id: webhook.id,
    webhook_url: webhook.url,
    save_secret_once: 'Store webhook.secret for X-Xquik-Signature verification; do not print it in logs.',
    idempotency_keys: ['deliveryId', 'streamEventId'],
    delivery_status: `/api/v1/webhooks/${webhook.id}/deliveries`,
    test
  };
}
Poll stored monitor events (free) 
async () => {
  const monitor_id = 'mon_123';
  const event_type = 'tweet.new';
  const page = await xquik.request('/api/v1/events', {
    query: { monitorId: monitor_id, eventType: event_type }
  });

  return {
    source: 'xquik_mcp',
    job: 'monitor_event_poll',
    monitor_id,
    event_type,
    rows: page.events.map(event => ({
      event_id: event.id,
      type: event.type,
      username: event.username ?? null,
      query: event.query ?? null,
      monitor_id: event.monitor_id,
      monitor_type: event.monitor_type,
      occurred_at: event.occurred_at,
      data: event.data
    })),
    has_more: page.has_more,
    next_cursor: page.next_cursor,
    next_query: page.next_cursor
      ? { monitorId: monitor_id, eventType: event_type, after: page.next_cursor }
      : null
  };
}
Run an extraction with a resumable handoff (subscription required) 
async () => {
  const body = {
    toolType: 'tweet_search_extractor',
    searchQuery: 'launch announcement',
    resultsLimit: 500
  };

  const estimate = await xquik.request('/api/v1/extractions/estimate', {
    method: 'POST',
    body
  });

  if (estimate.allowed === false) {
    return {
      source: 'xquik_mcp',
      job: 'tweet_search_extraction',
      status: 'blocked',
      error: estimate.error,
      credits_required: estimate.credits_required,
      credits_available: estimate.credits_available
    };
  }

  const job = await xquik.request('/api/v1/extractions', {
    method: 'POST',
    body
  });

  return {
    source: 'xquik_mcp',
    job: 'tweet_search_extraction',
    extraction_id: job.id,
    tool_type: job.tool_type,
    status: job.status,
    query: body.searchQuery,
    results_limit: body.resultsLimit,
    estimated_results: estimate.estimated_results,
    credits_required: estimate.credits_required,
    poll: `/api/v1/extractions/${job.id}`,
    export_after_complete: `/api/v1/extractions/${job.id}/export?format=json`
  };
}

​
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. 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: 10 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: 10 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. 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. 
async () => {
  const page = await xquik.request('/api/v1/x/tweets/search', {
    query: { q: 'from:xquikcom giveaway', limit: '50' }
  });

  return {
    source: 'xquik_mcp',
    job: 'tweet_search',
    query: 'from:xquikcom giveaway',
    rows: page.tweets.map(tweet => ({
      tweet_id: tweet.id,
      text: tweet.text,
      author: tweet.author,
      created: tweet['created'],
      url: tweet.url
    })),
    has_more: page.has_more,
    next_cursor: page.next_cursor
  };
}
Subscribe (free, returns checkout or billing portal URL) 
async () => {
  return xquik.request('/api/v1/subscribe', { method: 'POST' });
}

​
API endpoints

The server covers 120 operations across 10 categories:

Account, composition, and credits

24 operations across account, composition, and credits: account info, API keys, subscribe, X identity, compose, styles, drafts, radar, balance checks, top-ups, checkout status, and quick top-up.

Extractions and media

10 operations across extraction and media: giveaway draws, extraction jobs, estimates, exports, and media download.

Monitoring and webhooks

18 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: tweet search, tweet and 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 full catalog with parameters and response shapes.

​
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, API keys, 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 a subscription and available credits.

Write actions

Tweet, reply, like, retweet, follow, DM, profile, community, and media upload writes are metered.

Subscription-only refreshes

Fresh style analysis after the 7-day cache window requires an active subscription.
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: The sandbox attempts POST /api/v1/subscribe; when it returns a URL, the error includes it. Present that URL to the user.
  • 402 / no_credits / insufficient_credits: Free data already fetched is preserved. Call POST /api/v1/credits/topup or POST /api/v1/credits/quick-topup, then retry the failed metered call.
  • 429: Rate limited. Retry with exponential backoff.
  • API errors: Include status code and message in the response.
Last modified on May 22, 2026