> ## 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.

# AI agent MCP handoff for tweet search & exports

> Route AI agents between tweet search, follower exports, account actions, Docs MCP, API MCP, REST, SDKs, webhooks, and event replay. See tool examples.

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

Use this page when an AI agent needs to choose the right Xquik interface. It can search tweets, inspect profiles, export followers, or recover missed webhooks. Keep live calls narrow. Aggregate high-volume pages inside the sandbox. Store cursor state. Move durable jobs to REST, SDKs, or webhooks.

## Pick the agent interface

<CardGroup cols={2}>
  <Card title="Docs MCP" icon="book-open">
    Use `https://docs.xquik.com/mcp` when the agent needs public docs, API
    reference pages, examples, troubleshooting, or type definitions. It is
    read-only and requires no auth.
  </Card>

  <Card title="API MCP" icon="terminal">
    Use API MCP at `https://xquik.com/mcp` for live calls. Full account
    keys and OAuth tokens expose every catalog route. Guest `paid_reads` keys
    expose only the eligible GET routes. Current SDKs negotiate MCP
    `2026-07-28` through `server/discover`.
  </Card>

  <Card title="REST or SDK" icon="code">
    Use REST or generated SDKs when a service owns retries, cursor storage,
    file downloads, queues, or batch jobs outside the chat session.
  </Card>

  <Card title="Webhooks and replay" icon="history">
    Use monitor webhooks for fresh events and `GET /api/v1/events` when a
    receiver, queue, warehouse, or agent run needs replay.
  </Card>
</CardGroup>

## Use the default agent route

1. Search public docs or `llms.txt` before requesting current API data.
2. Use `docs` for product guidance. Use `search` before `xquik.request(...)` to confirm the endpoint path,
   required parameters, costs, and response shape.
3. Keep requested filters. Never add others. Call
   `xquik.request({ path, method?, query?, body? })` with the smallest useful page.
   Hosted MCP injects authentication and required idempotency headers.
4. Continue while `has_more` is true and `next_cursor` advances.
5. Return normalized rows, IDs, counts, samples, and cursors instead of full raw pages.
6. Hand long-running or replayable work to REST, SDKs, webhooks, or exports.

Credential lifecycle operations and direct saved-payment mutations are not in the MCP catalog. Guest wallet creation, status, and top-up also remain direct REST only.

A `402` creates no checkout. Report its payment choices, ask the user to choose an amount and option, then wait for explicit confirmation. A full account session may execute only an advertised account checkout action in its catalog. Never execute guest wallet routes through MCP.

```javascript theme={null}
async () => {
  return Object.entries(spec.paths).flatMap(([path, methods]) =>
    Object.entries(methods).flatMap(([method, operation]) =>
      path.includes("/x/tweets/search") || operation?.summary?.toLowerCase().includes("followers")
        ? [{ method: method.toUpperCase(), path, ...operation }]
        : [],
    ),
  );
};
```

## Route guest paid reads

An active guest key gives `search` and `execute` a read-only catalog of the eligible operations. The `docs` tool remains available. Every route appears in the [guest paid-read inventory](/guides/guest-wallets#eligible-paid-read-routes). Batch `GET /api/v1/x/tweets` accepts up to 100 tweet IDs.

The sandbox cannot execute writes, account actions, automations, billing, credential management, or any other read. OAuth and full account behavior remain unchanged.

If the guest key needs creation, activation status, or more credits, leave MCP and follow the [accountless guest wallet flow](/guides/guest-wallets) through direct REST:

* [`POST /api/v1/guest-wallets`](/api-reference/guest-wallets/create)
* [`GET /api/v1/guest-wallets/status`](/api-reference/guest-wallets/status)
* [`POST /api/v1/guest-wallets/topups`](/api-reference/guest-wallets/topup)

Creation and top-up require explicit user confirmation. Status polling does not create payment.

Never place the guest key or its creation `Idempotency-Key` in tool code, chat output, or shared agent state.

## Return stored rows

MCP returns normalized snake\_case fields, structured errors, and date-time fields as Unix seconds. Keep agents on `has_more` and `next_cursor` even when REST or SDK pages show camelCase response fields. Read a REST `createdAt` field as `created` in MCP results.

```javascript theme={null}
async () => {
  const query = "from:username MCP";
  const { result: page } = await xquik.request({
    path: "/api/v1/x/tweets/search",
    query: { q: query, limit: "50" },
  });

  return {
    source: "xquik_mcp",
    job: "tweet_search",
    query,
    rows: page.tweets.map((tweet) => ({
      tweet_id: tweet.id,
      text: tweet.text ?? null,
      author_id: tweet.author?.id ?? null,
      author_username: tweet.author?.username ?? null,
      created_at: tweet["created"] ?? null,
      url: tweet.url ?? null,
    })),
    has_more: page.has_more,
    next_cursor: page.next_cursor,
  };
};
```

## Follow cursor rules

| Source | Next request |
| - | - |
| MCP tweet, profile, follower, reply, timeline, community, and list pages | Pass `next_cursor` back as `cursor` when `has_more` is true. |
| MCP `/api/v1/draws`, `/api/v1/extractions`, and `/api/v1/events` | Pass `next_cursor` back as `cursor`. |
| MCP `/api/v1/radar` | Pass `next_cursor` back as `after`. |
| MCP `/api/v1/drafts` | Pass `next_cursor` back as `afterCursor`. |
| REST and generated SDKs | Follow the response fields documented on that endpoint page. |

Full account sessions can check `GET /api/v1/credits` before large reads.
Guest sessions receive balance and top-up context in `402`. The direct
REST guest status route reports the balance. Low balances can return
smaller pages. Zero affordable rows can return `402 insufficient_credits`.

For high-volume MCP reads:

* Deduplicate tweet or user rows by stable `id`
* Continue through empty pages when `has_more` is true
* Stop at the requested total, page cap, `has_more: false`, or `cursor_stalled` when cursors repeat. Keep output below 24,000 characters.

## Store handoff state

Store the values a later agent, service, or workflow needs to resume without
reading chat history.

```json theme={null}
{
  "agent_job_id": "mcp-research-q2",
  "surface": "api_mcp",
  "endpoint": "GET /api/v1/x/tweets/search",
  "query": "from:username MCP",
  "cursor_param": "cursor",
  "next_cursor": "DAACCgACGRElMJcAAA",
  "has_more": true,
  "webhook_id": "15",
  "delivery_id": "502",
  "stream_event_id": "9002",
  "event_replay_route": "GET /api/v1/events?cursor=9002",
  "export_route": "GET /api/v1/extractions/77777/export?format=json",
  "saved_fields": ["tweet_id", "author_username", "text", "url"]
}
```

Keep API keys, webhook secrets, raw request bodies, raw signatures, and full
headers out of chat transcripts, shared agent memory, spreadsheets, CRM rows,
and queue payloads.

## Know when to leave MCP

<CardGroup cols={2}>
  <Card title="File exports" icon="braces" href="/guides/response-formats-exports">
    Use extraction export endpoints for CSV, JSON, XLSX, Markdown, or PDF files.
  </Card>

  <Card title="Webhook receivers" icon="webhook" href="/guides/twitter-webhook-testing">
    Use signed webhooks when downstream systems need fresh monitor events.
  </Card>

  <Card title="Replay jobs" icon="database" href="/guides/brand-monitoring-workflow">
    Use stored events and delivery rows when receivers miss work.
  </Card>

  <Card title="SDK backends" icon="boxes" href="/sdks">
    Use SDKs when a backend owns retries, storage, and batch orchestration.
  </Card>
</CardGroup>

## Continue with focused references

<CardGroup cols={2}>
  <Card title="MCP tools reference" icon="terminal" href="/mcp/tools">
    Review Code Mode, OpenAPI-native tools, response contracts, and examples.
  </Card>

  <Card title="Docs MCP server" icon="book-open" href="/mcp/docs-mcp">
    Connect read-only documentation search beside the API MCP server.
  </Card>

  <Card title="No-code handoff" icon="workflow" href="/guides/no-code-workflow-handoff">
    Hand monitor events, exports, and direct reads to workflow platforms.
  </Card>

  <Card title="Webhook testing" icon="webhook" href="/guides/twitter-webhook-testing">
    Verify signed receivers before accepting production events.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.