Rate limits

Limits keep your creators’ OnlyFans accounts safe (OnlyFans watches for unnatural activity) and keep OnlyX fast for everyone. They apply per credential (an API key or an OAuth connection) unless the table says otherwise. MCP tool calls count against the credential they use.

The limits

What	Limit	Counted per
All requests	120 per 60 seconds	Credential
Sending messages (`POST /v1/conversations/{conversationId}/messages`)	30 per 60 seconds	Credential
	300 per hour	Creator (all credentials together)
Conversation counts (`GET /v1/conversations/counts`)	30 per 60 seconds	Credential
Reports (`/v1/stats/*`, all four together)	20 per 60 seconds	Credential
	One report prepared at a time; others get `202` warming	Workspace
Connection status (`GET /v1/creators/{creatorId}/connection`)	1 per 5 seconds	Creator and credential
Vault thumbnails (`GET /v1/creators/{creatorId}/media/{mediaId}/thumbnail`)	60 per 60 seconds	Credential
AI content changes (every `POST`, `PATCH`, `PUT` and `DELETE` under `/v1/creators/{creatorId}/ai-content`)	60 per 60 seconds	Credential
Adding creators (`POST /v1/creators`)	10 per 24 hours	Workspace
Creating connect links (`POST /v1/creators/{creatorId}/connect-link`)	20 per hour	Workspace
Creating tracking links (`POST /v1/creators/{creatorId}/tracking-links`)	10 per hour	Workspace
	5 per day	Creator
Replacing the welcome message (`PUT /v1/creators/{creatorId}/welcome-message`, dry runs included)	5 per hour	Creator
Turning review mode off (`PATCH /v1/creators/{creatorId}/ai-settings`)	6 per hour	Creator
Failed authentication with an unknown credential	30 per minute	IP address
OAuth client registration (`/oauth/register`)	20 per hour	IP address
OAuth token requests (`/oauth/token`)	60 per minute	IP address

A request counts against every limit that applies to it: a send counts toward the 120-request limit, the 30-sends limit and the creator’s hourly send limit. The failed-authentication limit only ever refuses credentials OnlyX does not recognize: over it, such requests get 429 instead of 401. A valid key is never refused because of other failures from the same address, and an expired or revoked credential always gets its normal 401.

Headers

Every /v1 response to an authenticated request tells you where you stand, for the tightest limit the request counted against:

Header	Meaning
`X-RateLimit-Limit`	The size of the limit that applies to this request
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	When the window resets, as Unix epoch seconds

GET /v1/me also returns your general limit as rateLimit: {"limit": 120, "windowSeconds": 60}.

When you hit a limit

You get 429 Too Many Requests with a Retry-After header (seconds) and the standard error body:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790431212
Content-Type: application/json

{"error":{"code":"RATE_LIMITED","message":"Too many requests. Try again in 12 seconds.","requestId":"req-0b7e2c9d4f1a8e36c5d4e3f2"}}

Wait at least Retry-After seconds before retrying. A 429 never performs the action, so retrying a write after waiting is safe; use the same Idempotency-Key anyway.

Backoff example

import random, time, requests

def request_with_backoff(session, method, url, max_attempts=6, **kw):
    for attempt in range(max_attempts):
        r = session.request(method, url, timeout=30, **kw)
        if r.status_code != 429:
            return r
        wait = int(r.headers.get("Retry-After", "1"))
        time.sleep(wait + random.uniform(0, 1))  # jitter avoids synchronized retries
    return r

async function fetchWithBackoff(url, options = {}, maxAttempts = 6) {
  let res;
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    res = await fetch(url, options);
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("Retry-After") ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000 + Math.random() * 1000)); // jitter
  }
  return res;
}

# curl treats 429 as transient and honors Retry-After
curl --retry 5 https://api.onlyx.ai/v1/creators \
  -H "Authorization: Bearer $ONLYX_API_KEY"

Staying under the limits

Watch X-RateLimit-Remaining and slow down before it reaches 0 instead of waiting for a 429.
Cache reads that change slowly: creators, reports, fan lists, tracking links.
Poll gently: connection status every 10 seconds at most while a creator signs in, message delivery every 5 to 10 seconds, the overview report only when Retry-After says so.
Page with limit=100 (or 50 for conversations) rather than many small pages.
Spread sends out. The creator-wide limit of 300 sends per hour applies whatever key you use, and a natural pace is better for the account anyway.
One key per integration. Each integration then has its own 120-per-minute budget and cannot starve another.

Errors: RATE_LIMITED and other retryable errors.
Idempotency: safe retries.

Get started

Guides

Reference topics

The limits

Headers

When you hit a limit

Backoff example

Staying under the limits

​The limits

​Headers

​When you hit a limit

​Backoff example

​Staying under the limits

​Related

The limits

Headers

When you hit a limit

Backoff example

Staying under the limits

Related