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

# Xquik platform architecture & X API workflows

> Learn how Xquik searches tweets, exports followers, monitors accounts, signs webhooks, isolates accounts, and enforces API rate limits for each account.

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

Xquik is a hosted service for tweet search, follower exports, profile lookup, monitors, webhooks, and X account actions.

You interact through the REST API, MCP server, SDKs, or dashboard.

You do not deploy Xquik infrastructure or configure X API credentials.

## Architecture overview

```text theme={null}
┌───────────────────────────────────────────────┐
│                    Clients                    │
│  REST API · MCP · SDKs · Dashboard · CLI     │
└──────────────────────┬────────────────────────┘
                       │ HTTPS
┌──────────────────────▼────────────────────────┐
│             Public Xquik Interfaces           │
│  Authentication · Rate Limits · Usage Gates  │
├───────────────────────────────────────────────┤
│  Read Service · Write Service · Webhooks     │
└──────────────────────┬────────────────────────┘
                       │
┌──────────────────────▼────────────────────────┐
│          Documented Responses & Events        │
└───────────────────────────────────────────────┘
```

### Components

<CardGroup cols={2}>
  <Card title="REST API" icon="braces">
    Documented operations at `https://xquik.com/api/v1/*` for apps,
    backends, scripts, and fine-grained pagination.
  </Card>

  <Card title="MCP server" icon="bot">
    3 tools, `docs`, `search`, and `execute`, at `https://xquik.com/mcp` for ChatGPT,
    Claude, Cursor, and agent workflows.
  </Card>

  <Card title="Dashboard" icon="layout-dashboard">
    Manage API keys, connected X accounts, monitors, extractions, draws,
    webhooks, media, billing, and support.
  </Card>

  <Card title="Monitoring & webhooks" icon="radio">
    Track accounts or keywords, store events, and deliver HMAC-signed webhook
    payloads with retry history.
  </Card>

  <Card title="Extractions & draws" icon="archive">
    Run stored jobs for followers, replies, quotes, retweeters, favoriters,
    search, articles, and giveaway draws.
  </Card>

  <Card title="Write actions" icon="send">
    Post tweets and replies, upload media, send DMs, follow, like, retweet,
    update profiles, and poll write status.
  </Card>
</CardGroup>

See [integration workflows](/guides/workflows) for end-to-end code examples using these components.

## Security model

### Authentication

Xquik REST uses API key authentication. API MCP accepts OAuth 2.1 or an
Xquik API key when the client supports secure request headers. ChatGPT custom
apps require OAuth and cannot present custom API keys.

<CardGroup cols={2}>
  <Card title="API header" icon="key-round">
    Send `x-api-key` on every REST API request. MCP clients can authenticate
    with the same Xquik API key.
  </Card>

  <Card title="Key format" icon="fingerprint">
    Keys start with `xq_` followed by 64 hex characters. The dashboard shows
    the full key only once.
  </Card>

  <Card title="One-time display" icon="shield-check">
    Xquik returns the full key only during creation. Store it in a secret manager.
  </Card>

  <Card title="Revocation" icon="ban">
    Revoked or inactive keys stop authenticating immediately and return `401`.
  </Card>

  <Card title="Audit trail" icon="clock">
    Account audit views show API-key activity.
  </Card>

  <Card title="OAuth 2.1" icon="lock-keyhole">
    MCP also supports [OAuth 2.1 with S256 PKCE](/oauth/overview) for clients
    that require delegated authorization.
  </Card>

  <Card title="Key management" icon="key-round">
    Create and revoke keys through the authenticated dashboard.
  </Card>
</CardGroup>

<Warning>
  Xquik shows API keys once at creation. Store them in a secret manager. You cannot retrieve a key after creation.
</Warning>

### Data isolation

Every API key belongs to a single user account. No key can read another user's data.

<CardGroup cols={2}>
  <Card title="Monitors" icon="radio">
    Account and keyword monitors belong to the user account that created them.
  </Card>

  <Card title="Events" icon="activity">
    Stored events resolve through account or keyword monitor ownership before
    returning data.
  </Card>

  <Card title="Webhooks" icon="webhook">
    Webhook endpoints, signing configuration, and delivery logs belong to one
    user.
  </Card>

  <Card title="Extractions" icon="archive">
    Extraction jobs, result pages, and exports belong to the user that created
    the job.
  </Card>

  <Card title="Draws" icon="gift">
    Giveaway draws, entries, and winner lists belong to the user that created
    the draw.
  </Card>

  <Card title="API keys" icon="key-round">
    API-key listing, creation, and revocation filter by the authenticated user
    ID.
  </Card>
</CardGroup>

A request for another user's resource returns `404 Not Found`, not `403`. Attackers cannot use the response to enumerate IDs.

### Authorization

Xquik uses a flat permission model. It has no roles, no RBAC, and no team workspaces.

* **One user, one account.** Each account has full access to all its own resources
* **API key scope.** A valid account API key can perform API-key-authorized operations for that account
* **API key management.** Listing, creating, and revoking keys require a same-origin dashboard session. API keys and OAuth bearer tokens cannot manage keys
* **Credit gates.** Creating extractions, draws, active monitors, media downloads, and X lookups require enough available credits. All webhook operations are free. Reading and managing stored jobs, monitors, and events is free. Active monitors cost 21 credits per hour.

## Rate limits

Xquik enforces rate limits per user account with a fixed-window counter algorithm. Each tier has an independent counter. Read counters reset every 1 second. Write and delete counters reset every 60 seconds.

<CardGroup cols={2}>
  <Card title="Read bucket" icon="database">
    `GET`, `HEAD`, and `OPTIONS` share a standard user limit of 500 requests per
    1 second.
  </Card>

  <Card title="Write bucket" icon="pen-line">
    `POST`, `PUT`, and `PATCH` share a standard user limit of 120 requests per
    60 seconds.
  </Card>

  <Card title="Delete bucket" icon="circle-x">
    `DELETE` requests have a limit of 60 requests per 60 seconds.
  </Card>

  <Card title="Retry window" icon="timer">
    Throttled reads return `Retry-After: 1`. Throttled writes and deletes
    return `Retry-After: 60`.
  </Card>
</CardGroup>

When you reach the limit, requests return `429 Too Many Requests` with a `Retry-After` header. Read throttles return `Retry-After: 1`. Write and delete throttles return `Retry-After: 60`.

See the [Rate Limits](/guides/rate-limits) guide for detailed explanations, backoff strategies, and client-side rate limiter code examples.

## Usage & billing

<CardGroup cols={3}>
  <Card title="Subscriptions" icon="credit-card">
    Starter, Pro, and Business plans run from USD 20 to USD 199 per month and
    include monthly credits.
  </Card>

  <Card title="Active monitors" icon="radio">
    Monitor slots are unlimited. Active monitors check every 1 second
    and cost 21 credits per active monitor-hour.
  </Card>

  <Card title="Credit top-ups" icon="wallet">
    Top up from USD 10. Credits cost USD 0.00015 each. See
    [Billing & Usage](/guides/billing#credit-top-ups).
  </Card>
</CardGroup>

### What counts as usage

<CardGroup cols={2}>
  <Card title="Credit-metered work" icon="gauge">
    Paid X reads, media downloads, trends, extraction estimates, extraction
    creation, monitor creation, active monitor hours, and draw execution can
    consume credits.
  </Card>

  <Card title="Credit access" icon="lock-keyhole">
    Tweet search, user and follower lookup, article lookup, media download,
    trends, draw creation, and publish actions require enough available credits.
  </Card>

  <Card title="Free management paths" icon="list-check">
    List, read, update, delete, export, test, and delivery-history paths stay
    free for draws, extractions, monitors, events, and webhooks.
  </Card>

  <Card title="Free utilities" icon="sparkles">
    Compose, cached styles, drafts, radar, account, API keys, X accounts,
    support, credit balance, and credit top-up endpoints are free.
  </Card>
</CardGroup>

See [Billing & Usage](/guides/billing) for credit costs and billing.

## Monitoring architecture

Xquik checks active account and keyword monitors every second.

```text theme={null}
X signals
    │
    ▼
Monitor processing ──▶ Stored events
    │
    ▼
Signed webhooks ──▶ Customer HTTPS endpoint
```

<CardGroup cols={2}>
  <Card title="Event types" icon="radio">
    Account monitors emit 10 tweet and 11 profile event types. Keyword
    monitors emit tweet types only.
  </Card>

  <Card title="Signed delivery" icon="shield-check">
    Xquik sends an HMAC-SHA256 signed HTTPS `POST` to each active webhook
    endpoint. Verify `X-Xquik-Signature`, `X-Xquik-Timestamp`, and
    `X-Xquik-Nonce`.
  </Card>

  <Card title="Retry schedule" icon="rotate-ccw">
    Failed deliveries retry until your endpoint returns `2xx`. A failing
    endpoint gets 1 retry at a time, at least every 15 minutes. A rejected
    delivery can delay new events by up to 15 minutes. Return `2xx` for events
    you skip.
  </Card>

  <Card title="Receiver timeout" icon="timer">
    Webhook receivers should return `2xx` within 10 seconds. Xquik records slow or
    non-`2xx` responses as failed attempts.
  </Card>

  <Card title="Event propagation" icon="activity">
    Events usually appear within seconds to minutes, depending on X stream
    timing and webhook receiver availability.
  </Card>
</CardGroup>

## Platform limitations

<CardGroup cols={2}>
  <Card title="Bookmarked tweets" icon="bookmark">
    Bookmarks and bookmark folders require a connected X account. Use
    [bookmarks](/api-reference/x/bookmarks) and
    [bookmark folders](/api-reference/x/bookmark-folders).
  </Card>

  <Card title="Export caps" icon="download">
    Extraction exports stop at 100,000 rows. PDF exports stop at
    10,000 rows. Supported formats: CSV, JSON, MD, MD Document, PDF, TXT, and
    XLSX.
  </Card>

  <Card title="Webhook retries" icon="rotate-ccw">
    Webhook deliveries have no attempt limit. Xquik retries each failure until
    it succeeds. Only you can pause or delete a webhook. Xquik keeps queued
    events until all deliveries finish. Events expire 30 days after Xquik creates
    them.
  </Card>

  <Card title="Monitor slots" icon="activity">
    Monitor slots are unlimited. Active monitors check every 1 second
    and cost 21 credits per active monitor-hour.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/x-api-quickstart">
    Make your first API call.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API key format, header requirements, and dual auth.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/guides/rate-limits">
    Fixed-window limits, backoff strategies, and code examples.
  </Card>

  <Card title="Billing & usage" icon="credit-card" href="/guides/billing">
    Pricing, credit allowances, and billing.
  </Card>
</CardGroup>

<div className="related-api-links">
  <Accordion title="Related tweet, reply & media APIs" icon="link">
    * Tweets: [Get tweet](/api-reference/x/get-tweet) · [Batch tweets](/api-reference/x/batch-tweets) · [Tweet thread](/api-reference/x/tweet-thread) · [Hidden replies](/api-reference/x/tweet-hidden-replies) · [Translate tweet](/api-reference/x/tweet-translation) · [Embed tweet](/api-reference/x/tweet-embed) · [Resolve links](/api-reference/x/resolve-links) · [Tweet subtitles](/api-reference/x/tweet-subtitles) · [X Article](/api-reference/x/get-article)
    * Analysis: [Sentiment analysis](/api-reference/x/sentiment-analysis) · [Brand mentions](/api-reference/x/brand-monitoring) · [News classification](/api-reference/x/news-classification) · [Market signals](/api-reference/x/market-signals) · [Viral score](/api-reference/x/viral-score) · [Classify posts](/api-reference/x/classify-tweets)
    * Engagement: [Tweet replies](/api-reference/x/tweet-replies) · [Quote tweets](/api-reference/x/tweet-quotes) · [Likers](/api-reference/x/favoriters) · [Reposters](/api-reference/x/retweeters) · [Check repost](/api-reference/x/tweet-repost-check)
    * Profiles: [User tweets](/api-reference/x/user-tweets) · [Batch user tweets](/api-reference/x/batch-user-tweets) · [User replies](/api-reference/x/user-replies) · [User likes](/api-reference/x/user-likes) · [User media](/api-reference/x/user-media) · [User highlights](/api-reference/x/user-highlights) · [User articles](/api-reference/x/user-articles)
    * Feeds: [List tweets](/api-reference/x/list-tweets) · [Trends](/api-reference/x/trends) · [Trend locations](/api-reference/x/trend-locations) · [Search Spaces](/api-reference/x/search-spaces) · [Get Space](/api-reference/x/get-space) · [Space replay](/api-reference/x/space-replay) · [Get broadcast](/api-reference/x/get-broadcast) · [Hashflags](/api-reference/x/hashflags) · [Search places](/api-reference/x/search-places) · [Download media](/api-reference/x/download-media)
  </Accordion>
</div>

<div className="related-api-links">
  <Accordion title="Related timeline, bookmark & notification APIs" icon="link">
    * Account feeds: [Home timeline](/api-reference/x/timeline) · [Notifications](/api-reference/x/notifications) · [Mentions](/api-reference/x/user-mentions)
    * Saved and private: [Bookmarks](/api-reference/x/bookmarks) · [Bookmark folders](/api-reference/x/bookmark-folders) · [DM history](/api-reference/x/dm-history)
  </Accordion>
</div>


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