REST API Overview

Xquik REST API v1 reads X data and runs automations.

All public X data reads need no connected X account. Every X write requires one. Private, account-scoped reads, including DMs and bookmarks, also require one. See Connect X account.

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

Accountless Paid Reads

Stripe-funded guest keys for 33 eligible GET routes

Base URL

https://xquik.com/api/v1

All endpoints are served over HTTPS only. Always use the full HTTPS 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 either format with OpenAPI tools or client generators. Xquik publishes the spec through RFC 9727 service discovery. API service discovery is published at:

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

Authentication

Account API keys can use x-api-key:

x-api-key: xq_your_api_key_here

Generate account keys from the API Keys dashboard. Xquik API keys can also use Authorization: Bearer xq_your_api_key_here. OAuth 2.1 Bearer tokens keep their granted account scopes. Accountless guest keys use Authorization: Bearer and have the fixed paid_reads scope. They work only on the 33 eligible paid-read routes after a verified Stripe webhook. See Authentication for every method.

Machine Payments Protocol

Seven fixed-price GET operations also accept anonymous MPP payments. The server returns a 402 with its WWW-Authenticate: Payment challenge and an optional guest wallet action. Your client can complete the MPP challenge or ask the user to confirm a

10 -

250 USD guest wallet. A failed request creates no checkout.

Accountless guest wallets

POST /api/v1/guest-wallets creates a one-use Stripe-hosted Payment Link after explicit user confirmation. It returns the guest key and status URL without requiring an account, email, or dashboard. The key remains inactive for paid reads until verified payment activates it. Anonymous requests to the 26 non-MPP paid reads return 401 with WWW-Authenticate: Bearer and a guest wallet action. The 7 direct MPP reads return 402 with a Payment challenge and the same action. Neither response creates checkout. See Accountless guest wallets for creation, polling, top-ups, scope boundaries, and MCP behavior.

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_api_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_api_key_here with your key. After 401, confirm the x-api-key header and xq_ prefix.

Integration readiness checklist

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

Authentication

Send a full account key or OAuth token for account operations. Use an active guest key on its 33 paid reads. Use direct MPP only on its 7 fixed-price operations. Handle the documented 401 and 402 contracts separately.

Response contract

Default REST examples use the v1 shape. Send xquik-api-contract: 2026-04-29 when your client expects snake_case, date-time fields as Unix seconds, structured errors, has_more, and next_cursor. The API MCP server sends this contract automatically.

Pagination

Use after with nextCursor on events, draws, extractions, and Radar. Use afterCursor on drafts. Use cursor with next_cursor on X data endpoints. De-duplicate stable IDs and reject repeated cursors.

Billing

Handle 402 no_credits and 402 insufficient_credits. Treat every payment_options action as an offer. Ask the user to select an amount and explicitly confirm before creating checkout.

Rate limits

Respect Retry-After. Read calls allow 300 per 1s. Writes allow 120 per 60s. Deletes allow 60 per 60s. Back off after repeated 429 rate_limit_exceeded responses.

Durable writes

Send a unique Idempotency-Key. Store the returned action. Poll statusUrl while terminal is false. Retry only when safeToRetry is true, using a new key.

Rate limits

Read requests

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

Write requests

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

Delete requests

DELETE requests use a separate 60 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

Treat every ID as an opaque string. IDs may use digits, UUIDs, or prefixes. Never parse them as numbers:

{ "id": "123456789" }

Default timestamps are ISO 8601 UTC

Default REST responses use ISO 8601 UTC strings. The normalized contract converts date-time fields to Unix seconds and renames createdAt to created:

{ "created": 1771929000 }

Default errors use string codes

Default REST errors return an error field with a machine-readable string 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 lacks usable billing access or enough credits. Existing available credits work without an active plan.

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 after for events, draws, and extractions. Pass it as afterCursor for drafts:

curl "https://xquik.com/api/v1/events?after=MjAyNi0wMi0yNFQxMDozMDowMC4wMDBa..." \
 -H "x-api-key: xq_your_api_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?q=xquik&cursor=DAABCgABGRnYttk__..." \
 -H "x-api-key: xq_your_api_key_here"

Cursors are opaque strings. Do not decode or construct them. Continue through empty pages while the response says more data exists. Stop and surface a pagination error when the next cursor is missing, unchanged, or already seen. 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_api_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. Date-only strings stay unchanged. A default createdAt field becomes created.

{
  "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."
  }
}

Pass next_cursor as cursor on most X data endpoints. Use after for events, draws, extractions, and radar. Use afterCursor for drafts.

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. Keyword monitors accept only the 10 tweet.* types above.

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

Create tweets, likes, retweets, follows, DMs, and profile updates.

Monitors

Check X accounts every second and receive signed webhook events.

Documentation Index

Monitors & Events

Draws & Extractions

X Data

X Write Actions

Account & Billing

Accountless Paid Reads

​Base URL

​OpenAPI spec

​Authentication

​Machine Payments Protocol

​Accountless guest wallets

​First request

​Integration readiness checklist

Authentication

Response contract

Pagination

Billing

Rate limits

Durable 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

Accountless guest wallets

First request

Integration readiness checklist

Rate limits

Conventions

Event types

Monitor events

Next steps