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

# Platform architecture

> How Xquik works. Architecture, security model, data isolation, rate limits, and platform limitations

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

Xquik is a hosted SaaS platform for X (Twitter) data. All data processing happens server-side. There is no infrastructure to deploy, no workers to manage, and no X API credentials to configure. You interact with Xquik through the REST API, MCP server, or dashboard.

## Architecture overview

```text theme={null}
┌──────────────────────────────────────────────────┐
│                    Clients                        │
│  REST API  ·  MCP Server  ·  Dashboard  ·  CLI   │
└──────────────────────┬───────────────────────────┘
                       │ HTTPS
┌──────────────────────▼───────────────────────────┐
│                  Xquik Server                     │
│  Next.js App Router  ·  API Routes  ·  MCP Host  │
├───────────────────────────────────────────────────┤
│  Auth  ·  Rate Limiter  ·  Usage Tracking         │
├───────────────────────────────────────────────────┤
│  Extraction Engine · Draw Engine · Monitors · Write API │
└──────────┬──────────────────────┬─────────────────┘
           │                      │
┌──────────▼──────────┐  ┌───────▼─────────────────┐
│     Database        │  │   Xquik Stream Service   │
│                     │  │  Real-time event         │
│                     │  │  processing & webhooks   │
└─────────────────────┘  └───────┬─────────────────┘
                                 │
                        ┌────────▼────────┐
                        │   X API Layer   │
                        └─────────────────┘
```

### Components

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

  <Card title="MCP server" icon="bot">
    2 tools, `explore` and `xquik`, 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 uses **API key authentication** for all API and MCP access. The MCP server also supports **OAuth 2.1** for platforms that require it (Claude.ai, ChatGPT Developer Mode).

<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="Stored hash" icon="shield-check">
    Xquik stores the SHA-256 key hash and display prefix, not the plaintext
    key.
  </Card>

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

  <Card title="Audit trail" icon="clock">
    Successful API-key checks update `lastUsedAt` for account audit views.
  </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="Session auth" icon="cookie">
    Dashboard login uses session cookies. API-key creation and revocation
    require session auth.
  </Card>
</CardGroup>

<Warning>
  API keys are shown once at creation. Store them securely. There is no way to retrieve a key after creation.
</Warning>

### Data isolation

Every API key is scoped to a single user account. There is no cross-user access.

<CardGroup cols={2}>
  <Card title="Monitors" icon="radio">
    Account and keyword monitors are scoped to the creating user account.
  </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>

Attempting to access another user's resources returns `404 Not Found` (not `403`), preventing enumeration attacks.

### Authorization

Xquik uses a flat permission model: no roles, no RBAC, no team workspaces.

* **One user, one account**: Each account has full access to all its own resources
* **API key = full access**: Any valid API key for an account can perform all operations that account is authorized for
* **API key management**: Use a dashboard session cookie to create the first API key. Existing API keys and OAuth bearer tokens can manage keys for the same account.
* **Subscription gates**: Creating extractions, draws, active monitors, media downloads, and X lookups require an active subscription or credits. All webhook operations (create, read, update, delete, deliveries, test) are always free. Reading, updating, deleting, exporting, and testing existing extractions, draws, monitors, and stored events is always free. Active instant monitors cost 21 credits per hour while enabled.

## Rate limits

Rate limits are enforced per user account using 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 10 requests per
    1 second.
  </Card>

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

  <Card title="Delete bucket" icon="circle-x">
    `DELETE` requests are limited to 15 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 the limit is reached, 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 instant 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 are priced at 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="Subscription-gated work" icon="lock-keyhole">
    Tweet search, user and follower lookup, article lookup, media download,
    trends, draw creation, and publish actions require an active subscription.
  </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 monitors X accounts and keyword queries in real time through a dedicated background service.

```text theme={null}
X Data Stream
       │
       ▼
┌─────────────────┐     ┌──────────────────┐
│  Xquik Stream   │────▶│    Database      │
│    Service      │     │                  │
└────────┬────────┘     └──────────────────┘
         │
         ▼
┌─────────────────┐
│ Webhook Delivery │
│ HMAC-signed POST │
│ 10 attempts, exp.│
│ backoff           │
└─────────────────┘
```

<CardGroup cols={2}>
  <Card title="Event types" icon="radio">
    Account monitors emit `tweet.new`, `tweet.reply`, `tweet.quote`, and
    `tweet.retweet`.
  </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 up to 10 attempts with exponential backoff: base 1
    second, multiplier 2x, max 60 seconds. `410 Gone` exhausts immediately.
  </Card>

  <Card title="Receiver timeout" icon="timer">
    Webhook receivers should return `2xx` within 10 seconds. Slow or
    non-`2xx` responses are recorded 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="Single region" icon="map-pin">
    Xquik currently runs as a single-region service. Do not assume multi-region
    replication.
  </Card>

  <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 are capped at 100,000 rows. PDF exports are capped 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 try up to 10 attempts. `410 Gone` exhausts immediately;
    other failures retry until delivered or exhausted.
  </Card>

  <Card title="Monitor slots" icon="activity">
    Monitor slots are unlimited. Active instant 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="/quickstart">
    Get up and running with 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>