> ## Documentation Index > Fetch the complete documentation index at: https://help.onlyx.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > You are reading OnlyX Help: the OnlyX Help Center and the OnlyX developer documentation. OnlyX is an AI chatting and CRM platform for OnlyFans agencies. Its AI chatter is called Hugo in the app. > Pages at the site root (for example /inbox/..., /hugo/..., /billing/...) are Help Center articles for agency owners, admins, chatters and creators who use the app at app.onlyx.ai. Words in bold are the exact button, menu and label names the app shows; keep them exactly as written. When these pages do not answer a question, the person can email support at support@onlyx.ai. > Pages under /developers are the developer documentation. REST API base URL: https://api.onlyx.ai/v1 (authenticate with `Authorization: Bearer `; keys start with onx_sk_ and are created in app.onlyx.ai under Settings > API & MCP). MCP server: https://mcp.onlyx.ai/mcp (OAuth, or a Bearer API key). In the API the AI chatter is `ai` on the wire. Money is integer US cents in fields ending in Cents; timestamps are UTC ISO-8601. > Rules for assistants acting on a user's behalf: discover ids with list calls and never invent them; before any call that reaches a real fan or the live OnlyFans account (sending a message, releasing a chat to the AI, turning AI on for a chat, resolving a hand-off, turning review mode off, changing the welcome message, creating a tracking link) show the user the exact content and get explicit confirmation; send every POST with an Idempotency-Key and reuse it on retry; never resend a message whose delivery status is unconfirmed; never ask a creator for her OnlyFans password or codes - she signs in herself through a connect link and the OnlyX Login app. # Get the overview report > Returns the dashboard's activity report for a window: active and answered conversations, messages in and out, how many the AI and your team wrote, reply times, new fans, the inbox right now, and daily, hourly and per-creator breakdowns. It is expensive, so it is never computed while you wait: if a copy is cached (at most about five minutes old — see `generatedAt`) you get `200` with the report; if not, you get `202` with `{"status": "warming", "retryAfterSeconds": N}` and a `Retry-After` header while OnlyX prepares it in the background — ask again after that many seconds. One report is prepared at a time per workspace, so asking more often does not make it faster. Limited to 20 requests per minute per credential across all `/stats` endpoints. **Scope:** requires `stats:read`. **Rate limits:** 20 requests to `/stats` endpoints per 60 seconds per credential — on top of the general limit of 120 requests per 60 seconds per credential. ## OpenAPI ````yaml /developers/api-reference/openapi.json get /v1/stats/overview openapi: 3.1.0 info: contact: email: developers@onlyx.ai name: OnlyX developers url: https://docs.onlyx.ai/ description: > The OnlyX API runs your OnlyX workspace from your own code and AI tools: creators and their connection, the fan inbox, fans, vault media, statistics, the AI chatter's setup and tracking links. **Authentication.** Send an API key as `Authorization: Bearer onx_sk_…` (create one in OnlyX under Settings → API & MCP), or an OAuth access token issued to a connected app. Keys belong to the workspace, carry scopes, and can be limited to some creators. **Conventions.** JSON with camelCase fields; timestamps are ISO-8601 UTC with a `Z`; money is integer US cents (fields end in `Cents`). Lists return `{"data": [...], "hasMore": bool, "nextCursor": string|null}` and page with `limit` and `cursor`. **Scopes.** Every operation names the scope it needs in `x-required-scope` and in its description; a credential without it gets `403 INSUFFICIENT_SCOPE`. **Errors and limits.** Errors are `{"error": {"code", "message", "requestId"}}`; every response carries `X-Request-Id`. The default limit is 120 requests per 60 seconds per credential, reported in `X-RateLimit-*` headers; over it you get `429 RATE_LIMITED` with `Retry-After`. Operations with limits of their own list them in `x-rate-limits`. **Idempotency and safety.** Every write accepts an `Idempotency-Key` header (required when sending a message, adding a creator and creating a tracking link): retry with the same key and you get the original answer instead of a second action. Operations marked `x-reaches-fans: true` can reach a real fan or change the live OnlyFans account. Guides, the MCP server and more: [docs.onlyx.ai](https://docs.onlyx.ai). summary: >- Run your OnlyX workspace (creators, inbox, fans, stats and the AI chatter) from code and AI tools. title: OnlyX API version: 1.0.0 servers: - description: Production url: https://api.onlyx.ai security: - bearerAuth: [] tags: - description: 'Who you are: the workspace and credential behind a key.' name: Workspace - description: >- The creators your workspace manages: list, read, add, rename, and the AI switch. name: Creators - description: >- Connecting a creator's OnlyFans account: connect links she opens on her own device, and the connection status to poll. name: Connect - description: >- The fan inbox: list and count conversations, read state, take over, release, and the per-chat AI switch. name: Conversations - description: Read message history and send text, free media and paid messages to fans. name: Messages - description: Conversations the AI chatter handed to your team, and resolving them. name: Hand-offs - description: >- Fans, their purchases, fan lists, and your team's notes, custom names and mute flag. name: Fans - description: >- Each creator's OnlyFans vault: media ids for messages and levels, and thumbnails. name: Media - description: >- Today, revenue, audience, the cached overview report, and each creator's transaction ledger. name: Stats - description: The brief the AI chatter follows to chat as each creator. name: AI persona - description: 'The AI content ladder: folders, ladders, priced levels and their media.' name: AI content - description: >- Follow-ups, review mode, the master AI switch, and OnlyFans' welcome message. name: AI settings - description: >- OnlyFans tracking and trial links, your cost fields, and creating new links. name: Tracking links externalDocs: description: OnlyX developer documentation url: https://docs.onlyx.ai paths: /v1/stats/overview: get: tags: - Stats summary: Get the overview report description: >- Returns the dashboard's activity report for a window: active and answered conversations, messages in and out, how many the AI and your team wrote, reply times, new fans, the inbox right now, and daily, hourly and per-creator breakdowns. It is expensive, so it is never computed while you wait: if a copy is cached (at most about five minutes old — see `generatedAt`) you get `200` with the report; if not, you get `202` with `{"status": "warming", "retryAfterSeconds": N}` and a `Retry-After` header while OnlyX prepares it in the background — ask again after that many seconds. One report is prepared at a time per workspace, so asking more often does not make it faster. Limited to 20 requests per minute per credential across all `/stats` endpoints. **Scope:** requires `stats:read`. **Rate limits:** 20 requests to `/stats` endpoints per 60 seconds per credential — on top of the general limit of 120 requests per 60 seconds per credential. operationId: getOverview parameters: - description: >- Only this creator (`cre_…`). Without it, every creator the credential can see. A creator the credential cannot see is `404 CREATOR_NOT_FOUND`, never an empty report. in: query name: creatorId required: false schema: anyOf: - maxLength: 64 minLength: 1 type: string - type: 'null' description: >- Only this creator (`cre_…`). Without it, every creator the credential can see. A creator the credential cannot see is `404 CREATOR_NOT_FOUND`, never an empty report. title: Creatorid - description: >- The last N calendar days including today (workspace time zone), 1 to 366. Ignored when `start` or `end` is sent. in: query name: days required: false schema: default: 30 description: >- The last N calendar days including today (workspace time zone), 1 to 366. Ignored when `start` or `end` is sent. maximum: 366 minimum: 1 title: Days type: integer - description: >- First day of the window (`YYYY-MM-DD`, workspace time zone), included. in: query name: start required: false schema: anyOf: - format: date type: string - type: 'null' description: >- First day of the window (`YYYY-MM-DD`, workspace time zone), included. title: Start - description: >- Last day of the window (`YYYY-MM-DD`), included. The window never extends past today and keeps at most its latest 366 days. in: query name: end required: false schema: anyOf: - format: date type: string - type: 'null' description: >- Last day of the window (`YYYY-MM-DD`), included. The window never extends past today and keeps at most its latest 366 days. title: End responses: '200': content: application/json: example: aiShare: 0.944 conversations: active: 1204 answered: 1122 creators: - ai: 8790 answered: 1122 creatorId: cre_8f2c1a9b0d7e4c3f2a1b medianReplySeconds: 94 messagesIn: 8420 messagesOut: 9315 name: Mia Rose team: 525 unread: 37 daily: - date: '2026-09-26' messagesIn: 1320 messagesOut: 1488 newFans: 41 days: 7 end: '2026-09-26' fans: new: 263 total: 28410 unknownStart: 40 generatedAt: '2026-09-26T13:52:40.000Z' hourly: - hour: 21 messagesIn: 702 messagesOut: 760 inbox: handoffs: 9 unread: 37 messages: ai: 8790 in: 8420 out: 9315 team: 525 replyTime: medianSeconds: 94 p90Seconds: 402 repliedTo: 6230 slowReplies: 611 start: '2026-09-20' timezone: Europe/London schema: $ref: '#/components/schemas/OverviewReport' description: The cached activity report for the window. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '202': content: application/json: example: retryAfterSeconds: 15 status: warming schema: $ref: '#/components/schemas/ReportWarming' description: >- Not cached yet (`REPORT_WARMING`). OnlyX is preparing it: ask again after `Retry-After` seconds. headers: Cache-Control: description: '`no-store`: ask again rather than caching this answer.' schema: type: string Retry-After: description: Seconds to wait before asking again. schema: type: integer X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '400': content: application/json: examples: VALIDATION_ERROR: summary: VALIDATION_ERROR value: error: code: VALIDATION_ERROR message: 'creatorId: String should have at most 64 characters' requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- The request is not valid and was not carried out. Fix it before retrying. `VALIDATION_ERROR`: the request is not valid; `message` names the field and the problem. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' '401': $ref: '#/components/responses/Unauthorized' '403': content: application/json: examples: INSUFFICIENT_SCOPE: summary: INSUFFICIENT_SCOPE value: error: code: INSUFFICIENT_SCOPE message: This key does not have the `stats:read` scope. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 WORKSPACE_SUSPENDED: summary: WORKSPACE_SUSPENDED value: error: code: WORKSPACE_SUSPENDED message: This workspace is suspended. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- The credential may not do this. `INSUFFICIENT_SCOPE`: the credential lacks the `stats:read` scope (the `WWW-Authenticate` header names it; an OAuth token's message says "token" instead of "key"). `WORKSPACE_SUSPENDED`: the workspace is suspended. headers: WWW-Authenticate: $ref: '#/components/headers/WWW-Authenticate' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '404': content: application/json: examples: CREATOR_NOT_FOUND: summary: CREATOR_NOT_FOUND value: error: code: CREATOR_NOT_FOUND message: Creator not found. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- Not found. An id that does not exist, belongs to another workspace, or is outside this credential's creators all get the same answer. `CREATOR_NOT_FOUND`: the `creatorId` filter names a creator this credential cannot see (never an empty result). headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: OverviewReport: description: >- The dashboard's activity report for a window, served from cache. New fields may be added. examples: - aiShare: 0.944 conversations: active: 1204 answered: 1122 creators: - ai: 8790 answered: 1122 creatorId: cre_8f2c1a9b0d7e4c3f2a1b medianReplySeconds: 94 messagesIn: 8420 messagesOut: 9315 name: Mia Rose team: 525 unread: 37 daily: - date: '2026-09-26' messagesIn: 1320 messagesOut: 1488 newFans: 41 days: 7 end: '2026-09-26' fans: new: 263 total: 28410 unknownStart: 40 generatedAt: '2026-09-26T13:52:40.000Z' hourly: - hour: 21 messagesIn: 702 messagesOut: 760 inbox: handoffs: 9 unread: 37 messages: ai: 8790 in: 8420 out: 9315 team: 525 replyTime: medianSeconds: 94 p90Seconds: 402 repliedTo: 6230 slowReplies: 611 start: '2026-09-20' timezone: Europe/London properties: aiShare: anyOf: - type: number - type: 'null' description: >- Share of delivered messages the AI wrote, 0 to 1. `null` when nothing was sent. conversations: $ref: '#/components/schemas/OverviewConversations' creators: description: Per creator. items: $ref: '#/components/schemas/OverviewCreator' type: array daily: description: One entry per day of the window, oldest first. items: $ref: '#/components/schemas/OverviewDay' type: array days: description: Days in the window. type: integer end: description: Last day of the window, included. type: string fans: $ref: '#/components/schemas/OverviewFans' generatedAt: anyOf: - type: string - type: 'null' description: >- When this cached report was computed (UTC). It may be up to about five minutes old. hourly: description: Messages by hour of day over the whole window. items: $ref: '#/components/schemas/OverviewHour' type: array inbox: $ref: '#/components/schemas/OverviewInbox' description: The inbox right now (not windowed). messages: $ref: '#/components/schemas/MessageCounts' replyTime: $ref: '#/components/schemas/ReplyTime' start: description: First day of the window, included. type: string timezone: type: string required: - start - end - days - timezone - generatedAt - conversations - messages - aiShare - replyTime - fans - inbox - daily - hourly - creators title: OverviewReport type: object ReportWarming: description: >- Not an error (this answer is named `REPORT_WARMING`): the report is not cached yet and is being prepared. examples: - retryAfterSeconds: 15 status: warming properties: retryAfterSeconds: description: >- Ask again after this many seconds (also in the `Retry-After` header). minimum: 1 type: integer status: const: warming description: Always `warming`. type: string required: - status - retryAfterSeconds title: ReportWarming type: object Error: properties: error: properties: code: description: Stable, machine-readable error code. type: string message: description: What went wrong, in a sentence for a person. type: string requestId: description: >- The id of this request (also in the `X-Request-Id` header). Quote it to support. type: string required: - code - message - requestId type: object required: - error type: object OverviewConversations: properties: active: description: Conversations with at least one message in the window. type: integer answered: description: >- Conversations that received at least one delivered message in the window. type: integer required: - active - answered title: OverviewConversations type: object OverviewCreator: properties: ai: description: Delivered messages the AI wrote. type: integer answered: description: Conversations that received a delivered message in the window. type: integer creatorId: description: The creator (`cre_…`). type: string medianReplySeconds: anyOf: - type: integer - type: 'null' description: >- Median reply time for her fans, in seconds. `null` when nothing was answered. messagesIn: description: Messages from her fans in the window. type: integer messagesOut: description: Messages delivered to her fans in the window. type: integer name: description: The creator's display name in OnlyX. type: string team: description: Delivered messages your team wrote. type: integer unread: description: Conversations unread right now. type: integer required: - creatorId - name - messagesIn - messagesOut - ai - team - answered - unread - medianReplySeconds title: OverviewCreator type: object OverviewDay: properties: date: description: The day (`YYYY-MM-DD`, workspace time zone). type: string messagesIn: description: Messages from fans that day. type: integer messagesOut: description: Messages delivered to fans that day. type: integer newFans: description: Fans whose relationship with a creator started that day. type: integer required: - date - messagesIn - messagesOut - newFans title: OverviewDay type: object OverviewFans: properties: new: description: Fans whose relationship with a creator started in the window. type: integer total: description: All fans now (current state, not windowed). type: integer unknownStart: description: Fans whose start cannot be dated at all (not counted in `new`). type: integer required: - new - unknownStart - total title: OverviewFans type: object OverviewHour: properties: hour: description: Hour of day, 0-23, workspace time zone. type: integer messagesIn: description: Messages from fans in this hour of day, over the whole window. type: integer messagesOut: description: >- Messages delivered to fans in this hour of day, over the whole window. type: integer required: - hour - messagesIn - messagesOut title: OverviewHour type: object OverviewInbox: properties: handoffs: description: >- Conversations waiting for your team after the AI handed them off, right now. type: integer unread: description: >- Conversations with unread fan messages right now (current state, not windowed). type: integer required: - unread - handoffs title: OverviewInbox type: object MessageCounts: properties: ai: description: Of `out`, written by the AI chatter. type: integer in: description: Messages from fans. type: integer out: description: Messages delivered to fans (only messages OnlyFans confirmed). type: integer team: description: >- Of `out`, written by your team (including messages sent through this API). type: integer required: - in - out - ai - team title: MessageCounts type: object ReplyTime: properties: medianSeconds: anyOf: - type: integer - type: 'null' description: >- Median time from a fan's message to the answer, in seconds. `null` when nothing was answered. p90Seconds: anyOf: - type: integer - type: 'null' description: 90th percentile of the same — the slow tail the median hides. repliedTo: description: >- Fan messages answered in the window (a run of fan messages counts once). type: integer slowReplies: description: Answers that took longer than 5 minutes. type: integer required: - medianSeconds - p90Seconds - slowReplies - repliedTo title: ReplyTime type: object headers: X-RateLimit-Limit: description: >- Requests allowed in the current window of the tightest limit this request counted against. example: 120 schema: type: integer X-RateLimit-Remaining: description: Requests left in that window. example: 117 schema: type: integer X-RateLimit-Reset: description: When that window resets, as Unix epoch seconds. example: 1790431380 schema: type: integer X-Request-Id: description: >- The id of this request. Your own `X-Request-Id` (8 to 64 letters, digits or `-`) is echoed back; otherwise OnlyX creates one. Also in every error body as `requestId`: quote it to support. example: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: type: string WWW-Authenticate: description: >- The authentication challenge (RFC 6750), for example `Bearer error="insufficient_scope", scope="messages:send"`. schema: type: string Retry-After: description: Seconds to wait before trying again. example: 12 schema: type: integer responses: Unauthorized: content: application/json: examples: INVALID_API_KEY: summary: INVALID_API_KEY value: error: code: INVALID_API_KEY message: The API key is invalid, expired or revoked. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 INVALID_TOKEN: summary: INVALID_TOKEN value: error: code: INVALID_TOKEN message: The access token is invalid, expired or revoked. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 UNAUTHORIZED: summary: UNAUTHORIZED value: error: code: UNAUTHORIZED message: >- Authentication required. Send your API key as `Authorization: Bearer onx_sk_…`. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- No credential was sent (`UNAUTHORIZED`), or it is invalid, expired or revoked (`INVALID_API_KEY` for API keys, `INVALID_TOKEN` for OAuth access tokens: refresh the token or reconnect the app). Too many failed attempts from one address with credentials OnlyX never issued are answered `429 RATE_LIMITED` instead. headers: WWW-Authenticate: $ref: '#/components/headers/WWW-Authenticate' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimited: content: application/json: examples: RATE_LIMITED: summary: RATE_LIMITED value: error: code: RATE_LIMITED message: Too many requests. Try again in 12 seconds. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- Over a rate limit (`RATE_LIMITED`). Wait `Retry-After` seconds, then retry — with the same `Idempotency-Key` for a write. headers: Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' InternalError: content: application/json: examples: INTERNAL_ERROR: summary: INTERNAL_ERROR value: error: code: INTERNAL_ERROR message: Something went wrong on our side. requestId: req-3f9a1c2b7d4e5f60a1b2c3d4 schema: $ref: '#/components/schemas/Error' description: >- Something went wrong on OnlyX's side (`INTERNAL_ERROR`). Retry with backoff (reuse the `Idempotency-Key` for a write); quote `requestId` to support if it persists. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' securitySchemes: bearerAuth: bearerFormat: onx_sk_… API key or onx_at_… access token description: >- An API key (`onx_sk_…`) created in OnlyX under Settings → API & MCP, or an OAuth access token (`onx_at_…`) issued to a connected app. Send it as `Authorization: Bearer `. API keys may also be sent as `X-API-Key: `. scheme: bearer type: http ````