REST API Overview

The Xquik REST API v1 provides programmatic access to X data and automation. Endpoints are organized into these categories:

Monitors & Events

Create account and keyword monitors, retrieve events, manage webhooks

Draws & Extractions

Run giveaway draws, extract tweet data

X Data

User lookups, tweet search, trends, media downloads

X Write Actions

Post tweets, like, retweet, follow, DM, profile updates

Account & Billing

Account info, API keys, drafts, styles, subscriptions

Base URL

https://xquik.com/api/v1

All endpoints are served over HTTPS only. Plain HTTP requests receive a 301 redirect to HTTPS. Always use the full base URL.

OpenAPI spec

The full API specification is available as an OpenAPI 3.1 document:

https://xquik.com/openapi.json

YAML is also available at:

https://docs.xquik.com/openapi.yaml

Use these with any OpenAPI-compatible tool (Postman, Insomnia, Swagger UI) or to generate client libraries. The spec follows RFC 9727 service discovery conventions. API service discovery is published at:

https://xquik.com/.well-known/api-catalog

Authentication

Pass your API key via the x-api-key header:

x-api-key: xq_YOUR_KEY_HERE

Generate keys from your dashboard. See Authentication for full details on key format, dual auth endpoints, and security best practices.

Machine Payments Protocol

31 X-API endpoints also accept anonymous MPP payments. The server returns a 402 challenge; your client pays via Tempo (USDC) and retries with a payment credential. No API key needed. See the MPP overview for eligible endpoints and pricing.

First request

Copy-paste this to verify your API key works:

curl -s https://xquik.com/api/v1/account \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

Response:

{
  "plan": "active",
  "monitorsAllowed": 9007199254740991,
  "monitorsUsed": 0,
  "monitorBilling": {
    "activeDailyEstimate": "0",
    "activeHourlyBurn": "0",
    "creditsPerActiveMonitorDay": "500",
    "creditsPerActiveMonitorHour": "21",
    "eventsIncluded": true,
    "instantCheckIntervalSeconds": 1,
    "unlimitedSlots": true
  },
  "creditInfo": {
    "balance": "140000",
    "lifetimePurchased": "140000",
    "lifetimeUsed": "0",
    "autoTopupEnabled": false,
    "autoTopupAmountDollars": 10,
    "autoTopupThreshold": "50000"
  }
}

Replace xq_YOUR_KEY_HERE with your actual API key from the dashboard. If you get 401, double-check that the header name is x-api-key (lowercase) and the key starts with xq_.

Integration readiness checklist

Run this checklist before connecting a production client, workflow builder, or agent to the API.

Authentication

Send x-api-key on subscription endpoints or use the documented MPP flow on eligible X data endpoints. Handle 401 unauthenticated, 402 no_subscription, or an MPP 402 payment challenge.

Response contract

Default REST examples use the v1 shape. Send xquik-api-contract: 2026-04-29 only when your client expects snake_case, structured errors, has_more, and next_cursor. This prevents field-name drift between generated clients, MCP calls, and hand-written REST code.

Pagination

Use after with nextCursor on events, draws, extractions, and drafts. Use cursor with next_cursor on X data endpoints. Handle missing pages, duplicate records, and opaque cursors.

Billing

Handle 402 no_credits and 402 insufficient_credits. Estimate extraction cost before creating extraction jobs so partial paid result pages, failed draws, or blocked jobs are expected states.

Rate limits

Respect Retry-After. Read calls are 60 per 1s, write calls are 30 per 60s, and delete calls are 15 per 60s. Back off on repeated 429 rate_limit_exceeded responses.

Ambiguous writes

Treat 202 x_write_unconfirmed as pending confirmation. Store writeActionId, call GET /x/write-actions/{id}, and do not retry-send while status is pending_confirmation.

Rate limits

Read requests

GET, HEAD, and OPTIONS requests share a 60 per 1s user bucket. Standard read throttles return Retry-After: 1.

Write requests

POST, PUT, and PATCH requests share a 30 per 60s user bucket. Throttled writes return Retry-After: 60.

Delete requests

DELETE requests use a separate 15 per 60s user bucket. Throttled deletes return Retry-After: 60.

Exceeding limits returns 429 rate_limit_exceeded with Retry-After and a JSON retryAfter field. See the Rate Limits guide for backoff implementations in multiple languages.

Conventions

IDs are strings

All IDs are returned as strings representing bigint values. Always treat IDs as opaque strings - never parse them as numbers:

{ "id": "123456789" }

Timestamps are ISO 8601 UTC

All timestamps use ISO 8601 format in UTC. Store and compare timestamps as strings or parse them into proper date objects:

{ "createdAt": "2026-02-24T10:30:00.000Z" }

Errors follow a consistent format

All errors return a JSON body with an error field containing a machine-readable error code:

{ "error": "error_code" }

Common errors:

400 validation

invalid_input means the request body, query, or path failed validation. Fix the schema, field types, or required parameters before retrying.

401 authentication

unauthenticated means the API key or bearer token is missing or invalid. Send x-api-key or a valid Authorization bearer token.

402 billing state

no_subscription, no_credits, and insufficient_credits mean the request needs an active plan, credit balance, or top-up before retrying.

404 missing resource

not_found means the requested resource does not exist or is not available to the authenticated account.

429 rate limit

rate_limit_exceeded includes Retry-After and JSON retryAfter. Wait for the window and retry with backoff.

502 read service retry

x_api_unavailable means the read service is temporarily unavailable. Retry with exponential backoff.

See Error Handling for the full error code list and handling strategies.

Cursor-based pagination

Platform endpoints
X endpoints

Events, draws, extractions, and drafts use cursor-based pagination. When more results exist, the response includes hasMore: true and a nextCursor value:

{
  "events": [],
  "hasMore": true,
  "nextCursor": "MjAyNi0wMi0yNFQxMDozMDowMC4wMDBa..."
}

Pass nextCursor as the after query parameter to fetch the next page:

curl "https://xquik.com/api/v1/events?after=MjAyNi0wMi0yNFQxMDozMDowMC4wMDBa..." \
 -H "x-api-key: xq_YOUR_KEY_HERE"

X data endpoints (/x/*) use a different pagination shape. When more results exist, the response includes has_next_page: true and a next_cursor value:

{
  "tweets": [],
  "has_next_page": true,
  "next_cursor": "DAABCgABGRnYttk__..."
}

Pass next_cursor as the cursor query parameter to fetch the next page:

curl "https://xquik.com/api/v1/x/tweets/search?query=xquik&cursor=DAABCgABGRnYttk__..." \
 -H "x-api-key: xq_YOUR_KEY_HERE"

Cursors are opaque strings - do not decode or construct them manually. Monitors, webhooks, and API keys return up to 200 items without pagination.

Opt-in response contract

v1 keeps the default response contract unchanged for existing clients. Send xquik-api-contract: 2026-04-29 to opt in to the normalized v1 response contract.

curl "https://xquik.com/api/v1/events" \
 -H "x-api-key: xq_YOUR_KEY_HERE" \
 -H "xquik-api-contract: 2026-04-29"

Opt-in responses use snake_case field names, Unix timestamps in seconds, structured error objects, has_more and next_cursor pagination fields, an object field on recognized resources, and prefixed IDs where available.

{
  "events": [],
  "has_more": true,
  "next_cursor": "MjAyNi0wMi0yNFQxMDozMDowMC4wMDBa..."
}

Legacy dependency failures that return 502 by default return 424 Failed Dependency in the opt-in contract:

{
  "error": {
    "type": "dependency_error",
    "code": "x_api_unavailable",
    "message": "Read service temporarily unavailable. Retry shortly."
  }
}

Event types

Monitor events

Used across monitors, webhooks, and events: Valid account monitor and webhook types: tweet.new, tweet.quote, tweet.reply, tweet.retweet, tweet.media, tweet.link, tweet.poll, tweet.mention, tweet.hashtag, tweet.longform, profile.avatar.changed, profile.banner.changed, profile.name.changed, profile.username.changed, profile.bio.changed, profile.location.changed, profile.url.changed, profile.verified.changed, profile.protected.changed, profile.pinned_tweet.changed, profile.unavailable.changed.

tweet.new

Original tweet posted by the monitored account or matching query. Used when no reply, quote, or retweet signal is present.

tweet.quote

Quote tweet posted by the monitored account or matching query. Classified when quote metadata is present.

tweet.reply

Reply posted by the monitored account or matching query. Classified from reply flags or reply target IDs.

tweet.retweet

Retweet posted by the monitored account or matching query. Classified from retweet flags or RT @ text.

Next steps

Error Handling

Handle errors gracefully with retries and fallbacks.

Rate Limits

Understand limits and implement backoff strategies.

Workflows

End-to-end examples: monitors, events, and webhooks.

X Data Endpoints

User lookups, tweet search, trends, and media downloads.

X Write Actions

Post tweets, like, retweet, follow, DM, and more.

Monitors

Track X accounts and receive real-time events.

Documentation Index

Monitors & Events

Draws & Extractions

X Data

X Write Actions

Account & Billing

​Base URL

​OpenAPI spec

​Authentication

​Machine Payments Protocol

​First request

​Integration readiness checklist

Authentication

Response contract

Pagination

Billing

Rate limits

Ambiguous writes

​Rate limits

Read requests

Write requests

Delete requests

​Conventions

400 validation

401 authentication

402 billing state

404 missing resource

429 rate limit

502 read service retry

​Event types

​Monitor events

tweet.new

tweet.quote

tweet.reply

tweet.retweet

​Next steps

Error Handling

Rate Limits

Workflows

X Data Endpoints

X Write Actions

Monitors

Base URL

OpenAPI spec

Authentication

Machine Payments Protocol

First request

Integration readiness checklist

Rate limits

Conventions

Event types

Monitor events

Next steps