{ "openapi": "3.1.0", "info": { "title": "GEOly Data API", "version": "1", "description": "Typed endpoints of the GEOly Data API (`x-geoly-stability: stable`): the account behind the key (GET /api/v1/quota, /api/v1/brand), the brand catalog (GET /api/v1/topics, /api/v1/prompts), monitoring records (GET /api/v1/prompts/{prompt_id}/records, /api/v1/records/{record_id}) and the incremental record feed (GET /api/v1/records), writes (POST /api/v1/prompts, POST /api/v1/prompts/{prompt_id}/runs) and windowed reports (POST /api/v1/reports/*). Authenticate with an API key bound to one brand; the brand is implied by the key and never appears in paths.\n\nStability: within /api/v1 the shape and meaning of every declared field is stable — fields are never removed, renamed or retyped, units never change, and enums only grow (response enums are open: ignore unknown values and unknown fields). Metric definitions follow the product and are recorded in the changelog. Breaking changes only ship under /api/v2.\n\nEnvelope: `{ data, page?, meta }`. `meta.quota` is the billing outcome of the call; `meta.schema_conformant` is false only if the report output drifted from this document (the data is still returned).\n\nPagination: send `limit` (and `cursor` from `page.next_cursor` for the next page, with exactly the same filters). `page.next_cursor === null` is the only end-of-list signal; `page.capped: true` means the position limit was reached before the end. GET /api/v1/prompts uses a true keyset cursor (ordered by created_at, id): a row whose sort key is unchanged and that still matches the filters is never skipped or repeated because other rows were added or archived meanwhile, and there is no position limit. It is not a snapshot: every page re-applies the filters, so a row archived before you reach it drops out of an active listing. `x-geoly-pagination` describes each list.\n\nErrors use one envelope `{error:{code,message,details?},meta}`; `error.code` is drawn from the closed list in `x-geoly-error-codes`. Branch on the HTTP status and `error.code`, never on `message`. Stable keys of `error.details`: errors[] ({param, reason, allowed?, message}), reason, required, retry_after_seconds, max_bytes, actual_bytes, _quota, and resource / id (404 NOT_FOUND of a single-resource endpoint such as GET /api/v1/prompts/{prompt_id}).\n\nBilling: each call is billed at the price in `x-geoly-cost` ({tier, base, unit, long_window_multiplier, guard_rpm}: nominal price per call in credits, the same as the matching GEOly MCP tool (GET /api/v1/records has none: it is offered only on this API, so its price and guard are its own), against the MCP credits pool; tier \"free\" with base 0 = not charged — this includes operations whose matching MCP tool is registered as not charged (charged:false: POST /api/v1/prompts and POST /api/v1/prompts/{prompt_id}/runs), so no nominal price is declared for them; guard_rpm is the per-organization requests-per-minute guard of that endpoint — counted per organization together with the same organization's calls of the matching GEOly MCP tool on the other surfaces (MCP, Agent API)). The billing outcome of every call is in `meta.quota`. A monitoring run still consumes monitoring credits, a separate pool, as described on that operation.\n\nThe HTTP tool wrappers under /api/v1/tools and /api/v1/tools/{tool} are retired: every method answers 410 TOOL_SURFACE_RETIRED, and for a known tool details.replacement names the resource endpoint. Use these resource endpoints. MCP and Agent API remain available." }, "servers": [ { "url": "https://app.geoly.ai" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Records", "description": "Monitoring records and optional full answer text." }, { "name": "Account", "description": "The organization, credits and brand behind this API key." }, { "name": "Catalog", "description": "Topics and prompts of the brand behind this API key (GET, no metrics computed; the price of each operation is in x-geoly-cost)." }, { "name": "Reports", "description": "Windowed brand-visibility reports (POST with a JSON body; nothing is created)." } ], "x-geoly-error-codes": [ { "code": "INVALID_BODY", "status": 400, "retryable": false, "write_retry": null, "charged": "none", "description": "Request body is not a JSON object (or not valid JSON). Rejected before execution; not charged." }, { "code": "INVALID_ARGUMENT", "status": 400, "retryable": false, "write_retry": null, "charged": "none", "description": "Arguments do not match the input schema (unknown parameter, wrong type, invalid enum value, missing required field), or an argument the tool could only reject after looking it up (unknown topic / country / platform code, malformed date window, ambiguous name …; details.reason carries the original tool code when there is one). Not charged: rejected before execution, or refunded." }, { "code": "INVALID_CURSOR", "status": 400, "retryable": false, "write_retry": null, "charged": "none", "description": "The cursor is malformed or was issued for a different query. Drop it and start over." }, { "code": "IDEMPOTENCY_KEY_INVALID", "status": 400, "retryable": false, "write_retry": null, "charged": "none", "description": "Idempotency-Key header is present but malformed." }, { "code": "FAILED_PRECONDITION", "status": 400, "retryable": false, "write_retry": null, "charged": "depends", "description": "The request is valid but the current state does not allow it. details.reason says why: platform_not_enabled (the AI platform is not purchased for this brand) and locale_required (pass country + language; details.availableLocales lists them) are charged the minimum call fee under the current billing rule (meta.quota.charge = \"min_fee\"); a write conflict (name already taken …, details.reason = the original tool code) or an organization without brands is not charged. On the report endpoints, details.reason = request_rejected (the report rejected the arguments only after looking them up, e.g. \"Brand not found\", \"No brand in scope.\") is billed as the report settled — usually the full base price of the report; meta.quota.charge says which." }, { "code": "UNAUTHORIZED", "status": 401, "retryable": false, "write_retry": null, "charged": "none", "description": "API key missing, invalid, revoked, expired, or its creator left the organization; on the tool surface also a credential that is not tied to a user (raised while the tool runs). Not charged." }, { "code": "SUBSCRIPTION_INACTIVE", "status": 402, "retryable": false, "write_retry": null, "charged": "none", "description": "The organization has no active subscription (checked at authentication, or by the tool for the organization that owns the referenced resource). Not charged." }, { "code": "QUOTA_EXCEEDED", "status": 402, "retryable": true, "write_retry": "safe", "charged": "none", "description": "MCP credits used up for this period. Retry after the quota resets, or upgrade." }, { "code": "ORG_NOT_ELIGIBLE", "status": 402, "retryable": false, "write_retry": null, "charged": "none", "description": "The organization's plan does not include this tool." }, { "code": "PLAN_LIMIT_REACHED", "status": 402, "retryable": false, "write_retry": null, "charged": "none", "description": "A plan limit (brands, prompts …) is reached. Upgrade or free a slot." }, { "code": "API_KEY_BRAND_REQUIRED", "status": 403, "retryable": false, "write_retry": null, "charged": "none", "description": "The credential is not an API key bound to a brand (legacy org tokens and OAuth tokens are not served here)." }, { "code": "ORG_SELECTION_REQUIRED", "status": 403, "retryable": false, "write_retry": null, "charged": "none", "description": "The credential spans several organizations and none was selected." }, { "code": "ORGANIZATION_REQUIRED", "status": 403, "retryable": false, "write_retry": null, "charged": "none", "description": "The credential has no accessible organization." }, { "code": "PERMISSION_DENIED", "status": 403, "retryable": false, "write_retry": null, "charged": "none", "description": "The credential is not permitted to do this: denied at authentication (non-API-key credentials; details.reason carries the original reason), a resource read/write permission the key was not granted, or an id outside this key's brand / organization. Not charged." }, { "code": "REPORT_NOT_FOUND", "status": 404, "retryable": false, "write_retry": null, "charged": "none", "description": "Unknown report name in POST /api/v1/reports/{report}; see the API reference for the list. Not charged." }, { "code": "NOT_FOUND", "status": 404, "retryable": false, "write_retry": null, "charged": "depends", "description": "The referenced id / name does not exist for this brand. Billing depends on how the tool reports it (see meta.quota.charge): a not-found returned in the tool result keeps the tool's own settlement, receipt also in error.details._quota — the call-priced prompt and record detail reads (POST /api/v1/reports/prompt-overview, GET /api/v1/records/{record_id}) are charged as one call (\"charged\"), audit detail and search-query filters the minimum call fee (\"min_fee\"); a not-found raised while the tool runs (topic_name, brand_id …) is refunded (\"refunded\"); one rejected while resolving the scope (before execution) is not charged (\"unbilled\"); free tools and free endpoints report \"free\"." }, { "code": "METHOD_NOT_ALLOWED", "status": 405, "retryable": false, "write_retry": null, "charged": "none", "description": "HTTP method not supported on this path; see the Allow header." }, { "code": "IDEMPOTENCY_KEY_REUSED", "status": 409, "retryable": false, "write_retry": null, "charged": "none", "description": "The Idempotency-Key was already used with a different request body." }, { "code": "REQUEST_IN_PROGRESS", "status": 409, "retryable": true, "write_retry": "after_check", "charged": "none", "description": "A request with the same Idempotency-Key is still running. Retry with the same key after Retry-After." }, { "code": "IDEMPOTENCY_OUTCOME_UNKNOWN", "status": 409, "retryable": false, "write_retry": null, "charged": "depends", "description": "The outcome of this write, or of an earlier attempt with the same Idempotency-Key, cannot be determined: it may have been applied in part or in full. error.message carries the tool message when there is one. Check the resource with a GET before retrying; with a key, retry only with a new key." }, { "code": "TOOL_SURFACE_RETIRED", "status": 410, "retryable": false, "write_retry": null, "charged": "none", "description": "The HTTP tool wrappers under /api/v1/tools and /api/v1/tools/{tool} are retired. Answered for every method before authentication; nothing runs and nothing is charged. For a known tool details.replacement names the resource endpoint: one replacement object, or an array of them for a tool with several views or several replacements. Every replacement object has method and path and may carry when (the old arguments it replaces, for example {view: \"table\"} or {section: \"board\"}) and note (marks a replacement that is not drop-in). details.openapi points to this specification." }, { "code": "PAYLOAD_TOO_LARGE", "status": 413, "retryable": false, "write_retry": null, "charged": "none", "description": "Request body exceeds 64 KB." }, { "code": "UNSUPPORTED_MEDIA_TYPE", "status": 415, "retryable": false, "write_retry": null, "charged": "none", "description": "Request body must be application/json." }, { "code": "QUERY_TOO_EXPENSIVE", "status": 422, "retryable": false, "write_retry": null, "charged": "none", "description": "The query would scan too much data. Narrow the window / filters." }, { "code": "RESPONSE_TOO_LARGE", "status": 422, "retryable": false, "write_retry": null, "charged": "none", "description": "The serialized response exceeds the 4 MB limit for one API response (details.max_bytes / details.actual_bytes). Lower page_size / limit or narrow the filters. Decided before settlement; not charged." }, { "code": "RATE_LIMITED", "status": 429, "retryable": true, "write_retry": "safe", "charged": "none", "description": "Per-credential requests-per-minute limit. Honor Retry-After." }, { "code": "GUARDED_RATE_LIMITED", "status": 429, "retryable": true, "write_retry": "safe", "charged": "none", "description": "Per-tool rate guard on a heavy query. Honor Retry-After." }, { "code": "BUSY", "status": 429, "retryable": true, "write_retry": "safe", "charged": "none", "description": "Too many concurrent tool calls for this credential / organization. Honor Retry-After." }, { "code": "BUDGET_EXCEEDED", "status": 429, "retryable": true, "write_retry": "safe", "charged": "none", "description": "Organization hourly database-seconds budget exhausted. Honor Retry-After; pace with X-DB-Budget-*." }, { "code": "INTERNAL_ERROR", "status": 500, "retryable": true, "write_retry": "after_check", "charged": "none", "description": "Unexpected server error. Retry once with backoff; report the Request-Id if it persists." }, { "code": "TOOL_TIMEOUT", "status": 503, "retryable": true, "write_retry": "after_check", "charged": "none", "description": "The call hit its time limit (error.details / error.message carry narrowing hints). Not charged." }, { "code": "OVERLOADED", "status": 503, "retryable": true, "write_retry": "after_check", "charged": "none", "description": "The data layer is overloaded. Not charged; retry later." }, { "code": "CIRCUIT_OPEN", "status": 503, "retryable": true, "write_retry": "safe", "charged": "none", "description": "The tool is temporarily disabled after repeated failures. Not charged; honor Retry-After." }, { "code": "TOOL_FAILED", "status": 503, "retryable": true, "write_retry": "after_check", "charged": "none", "description": "A read failed and the call was refunded (charge \"refunded\", occasionally \"refund_pending\"; the receipt is in error.details._quota). Not charged; retry later." }, { "code": "FEED_NOT_READY", "status": 503, "retryable": true, "write_retry": "safe", "charged": "none", "description": "The record feed is not ready: its dedicated index is missing or invalid, or the database role cannot see all in-flight transactions to place a safe watermark. No fallback table scan is performed and no checkpoint advances." }, { "code": "IDEMPOTENCY_UNAVAILABLE", "status": 503, "retryable": true, "write_retry": "safe", "charged": "none", "description": "The persistent claim could not be acquired. No write was executed, and retrying with the same key never executes twice. If the failed claim could not be cleaned up, the retry answers REQUEST_IN_PROGRESS for up to 5 minutes and then IDEMPOTENCY_OUTCOME_UNKNOWN; in that case check with a GET and use a new key." } ], "paths": { "/api/v1/records": { "get": { "operationId": "listRecordsFeed", "summary": "Incremental completed records and subsequent changes", "description": "Completed records ordered by changed_at then id, not by record date, so a late completion appears at its completion update. Uses a dedicated index and a safe watermark at least five minutes behind database time; a long-running database transaction that has already written holds the watermark at five minutes before its start until it ends, and polls in that time return nothing newer but are still billed. Scan work is bounded, so an empty page can have next_cursor. Follow next_cursor until it is null, then save page.sync_cursor and poll with it; every 5 to 15 minutes is enough, because nothing newer than the watermark is returned. Bound the first sync with updated_since rather than business_date_from, which filters inside each scanned batch and does not shorten the scan. With a cursor, updated_since is ignored; keep limit, business_date_from and include unchanged. Repeated records are updates: upsert by id. Analysis fields are read-time values: mention_rank backfills do not advance changed_at, so a rank change alone is not re-emitted. Deletions and records that leave completed are not emitted either. Reconcile by starting a separate pass without a cursor from an updated_since rewound at least 24 hours (a rewound updated_since sent together with a saved cursor is ignored and reconciles nothing), or by re-reading records by record date. Optional answer_text and citations expansions; citations cap at 30 with a flag. Every call, including an empty poll, is billed at the price in x-geoly-cost.", "tags": [ "Records" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "light", "base": 1, "unit": "call", "long_window_multiplier": null, "guard_rpm": 20 }, "x-geoly-required-permission": "prompt:read", "x-geoly-pagination": { "style": "feed", "limit_param": "limit", "max_limit": 100, "cursor_param": "cursor", "next_cursor_path": "$.page.next_cursor", "checkpoint_path": "$.page.sync_cursor", "scan_limit": 1000 }, "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "cursor", "in": "parameters", "type": "cursor" } ], "outputs": { "nextCursor": "$.page.next_cursor" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "name": "updated_since", "in": "query", "required": false, "description": "Initial inclusive lower bound on changed_at for the first page (UTC with milliseconds). Ignored when cursor is present.", "schema": { "default": "1970-01-01T00:00:00.000Z", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, { "name": "business_date_from", "in": "query", "required": false, "description": "Optional earliest business day; filters inside each scanned batch and does not shorten the scan (UTC+8 business day, YYYY-MM-DD).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "answer_text", "citations", "answer_text,citations" ] } } ], "responses": { "200": { "description": "Incremental completed records and subsequent changes. `data` follows RecordFeed when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordFeedEnvelope" } } } }, "400": { "description": "INVALID_ARGUMENT (unknown query parameter, non-integer or out-of-range number, invalid enum value — details.errors[] lists each {param, reason, allowed?}) / INVALID_CURSOR (the cursor is malformed, or limit, business_date_from or include differ from the request that issued it; resend them unchanged, or start a new pass from updated_since). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "RESPONSE_TOO_LARGE: response exceeds 4 MB; omit include=answer_text to retrieve metadata. Rejected before settlement.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED / FEED_NOT_READY (the dedicated feed index or the safe watermark is not available; no fallback scan was run). Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/prompts": { "post": { "operationId": "createPrompt", "summary": "Create a monitoring prompt", "description": "Creates a prompt under the API key brand. Returns 201 and Location. Optional Idempotency-Key prevents duplicate execution; successful results replay for 24 hours. Unknown write outcomes are never automatically retried. tags_state reports whether every requested tag was read back (saved), some were not saved (partial) or the saved tags could not be confirmed (unavailable); tags_warning explains anything but saved. The prompt exists in all three cases.", "tags": [ "Catalog" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "free", "base": 0, "unit": null, "long_window_multiplier": null, "guard_rpm": null }, "x-geoly-required-permission": "prompt:write", "x-geoly-pagination": { "style": "none" }, "x-geoly-idempotency": { "header": "Idempotency-Key", "window_hours": 24, "unknown_outcome": "inspect_resource_do_not_retry", "write_outcome": "Every error response carries details.write_outcome: not_started (nothing was written; retry with the same key) or unknown (inspect the resource; with a key, retry only with a new key)." }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_\\-:.]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptRequest" } } } }, "responses": { "201": { "description": "Create a monitoring prompt. `data` follows CreatedPrompt when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Location": { "schema": { "type": "string" } }, "Idempotent-Replayed": { "schema": { "type": "string", "const": "true" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedPromptEnvelope" } } } }, "400": { "description": "INVALID_BODY / INVALID_ARGUMENT (unknown field, wrong type, missing required field — details.errors[] lists each {param, reason}; or an argument the tool rejected after looking it up, details.reason = the tool code) / IDEMPOTENCY_KEY_INVALID / FAILED_PRECONDITION (the current state does not allow the write; details.reason = the tool code, e.g. PROMPT_ARCHIVED). Rejected before anything is written: details.write_outcome = not_started.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "PLAN_LIMIT_REACHED (a plan limit such as the prompt limit; details.reason = the tool code) / QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged; details.write_outcome = not_started.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the write permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_NOT_FOUND (unknown report name; not charged) / NOT_FOUND (a referenced id does not exist for this brand; billing in meta.quota.charge).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED / REQUEST_IN_PROGRESS / IDEMPOTENCY_OUTCOME_UNKNOWN. IDEMPOTENCY_OUTCOME_UNKNOWN is also returned without a key when the outcome cannot be determined (for example a failed dispatch); error.message carries the tool message and meta.quota the receipt. An unknown outcome must not be retried blindly.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE: request body exceeds 64 KB.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send the body as application/json.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "QUERY_TOO_EXPENSIVE (narrow the window / filters) / RESPONSE_TOO_LARGE (the response exceeds 4 MB — lower limit or narrow the filters; decided before settlement, not charged).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal failure. The write may have completed; inspect before retrying.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "IDEMPOTENCY_UNAVAILABLE / TOOL_TIMEOUT / OVERLOADED. Inspect details.write_outcome: only not_started is safe to retry with the same key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "operationId": "listPrompts", "summary": "Prompts of the brand (keyset-paginated catalog)", "description": "The prompt list straight from the prompt table: text, country, status, topic, tags, timestamps and whether the text names the brand — no metrics (use POST /api/v1/reports/prompts for per-prompt visibility). Ordered by (created_at, id) ascending with a true keyset cursor: a row whose (created_at, id) stays the same and that still matches the filters is never skipped or repeated because others were added or archived meanwhile; there is no snapshot — a row archived before you reach it drops out of an active listing, and new rows appear at the end. Follow page.next_cursor until it is null; page.total counts every matching row. Free (no credits); no metrics are computed. Guarded at 200 requests per minute per organization: one bucket for GET /api/v1/prompts, GET /api/v1/prompts/{prompt_id} and the same organization's get_prompt_list view=catalog calls on the GEOly MCP / Agent API — separate from the prompts report's bucket.", "tags": [ "Catalog" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "free", "base": 0, "unit": null, "long_window_multiplier": null, "guard_rpm": 200 }, "x-geoly-required-permission": "prompt:read", "x-geoly-pagination": { "style": "keyset", "order": [ "created_at", "id" ], "limit_param": "limit", "max_limit": 200, "cursor_param": "cursor", "next_cursor_path": "$.page.next_cursor" }, "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "cursor", "in": "parameters", "type": "cursor" } ], "outputs": { "nextCursor": "$.page.next_cursor" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Rows per page (1–200).", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from page.next_cursor. Must be sent with exactly the same status, topic_id and limit.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } }, { "name": "status", "in": "query", "required": false, "description": "Monitored prompts (default) or archived ones. GET /api/v1/prompts/{prompt_id} returns a prompt in either state.", "schema": { "default": "active", "type": "string", "enum": [ "active", "archived" ] } }, { "name": "topic_id", "in": "query", "required": false, "description": "Only prompts of this topic (an id from GET /api/v1/topics); \"_none\" = prompts without a topic.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "Prompts of the brand (keyset-paginated catalog). `data` follows PromptList when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptListEnvelope" } } } }, "400": { "description": "INVALID_ARGUMENT (unknown query parameter, non-integer or out-of-range number, invalid enum value — details.errors[] lists each {param, reason, allowed?}) / INVALID_CURSOR (the cursor is malformed or belongs to another query — other filters or limit; drop it and start over). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/prompts/{prompt_id}/runs": { "post": { "operationId": "createPromptRun", "summary": "Trigger monitoring for a prompt", "description": "Returns 202 when work was dispatched, otherwise 200 when naturally deduplicated. Location points to monitoring records. Consumes monitoring credits through the existing trigger. Refusals decided before anything is written (plan prompt limit, archived prompt, no allowed or available platform, expired plan) return 4xx with details.reason set to the original tool code and details.write_outcome = not_started; the idempotency key is released. Optional Idempotency-Key uses a 24-hour completed-result window; unknown outcomes require inspection, never a blind retry.", "tags": [ "Records" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "free", "base": 0, "unit": null, "long_window_multiplier": null, "guard_rpm": null }, "x-geoly-required-permission": "monitoring_trigger:write", "x-geoly-pagination": { "style": "none" }, "x-geoly-idempotency": { "header": "Idempotency-Key", "window_hours": 24, "unknown_outcome": "inspect_resource_do_not_retry", "write_outcome": "Every error response carries details.write_outcome: not_started (nothing was written; retry with the same key) or unknown (inspect the resource; with a key, retry only with a new key)." }, "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "description": "Resource id for this API key brand.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_\\-:.]{8,128}$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptRunRequest" } } } }, "responses": { "200": { "description": "Trigger monitoring for a prompt. `data` follows PromptRun when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Location": { "schema": { "type": "string" } }, "Idempotent-Replayed": { "schema": { "type": "string", "const": "true" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptRunEnvelope" } } } }, "202": { "description": "Trigger monitoring for a prompt. `data` follows PromptRun when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Location": { "schema": { "type": "string" } }, "Idempotent-Replayed": { "schema": { "type": "string", "const": "true" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptRunEnvelope" } } } }, "400": { "description": "INVALID_BODY / INVALID_ARGUMENT (unknown field, wrong type, missing required field — details.errors[] lists each {param, reason}; or an argument the tool rejected after looking it up, details.reason = the tool code) / IDEMPOTENCY_KEY_INVALID / FAILED_PRECONDITION (the current state does not allow the write; details.reason = the tool code, e.g. PROMPT_ARCHIVED). Rejected before anything is written: details.write_outcome = not_started.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "PLAN_LIMIT_REACHED (a plan limit such as the prompt limit; details.reason = the tool code) / QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged; details.write_outcome = not_started.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the write permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_NOT_FOUND (unknown report name; not charged) / NOT_FOUND (a referenced id does not exist for this brand; billing in meta.quota.charge).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED / REQUEST_IN_PROGRESS / IDEMPOTENCY_OUTCOME_UNKNOWN. IDEMPOTENCY_OUTCOME_UNKNOWN is also returned without a key when the outcome cannot be determined (for example a failed dispatch); error.message carries the tool message and meta.quota the receipt. An unknown outcome must not be retried blindly.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE: request body exceeds 64 KB.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send the body as application/json.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "QUERY_TOO_EXPENSIVE (narrow the window / filters) / RESPONSE_TOO_LARGE (the response exceeds 4 MB — lower limit or narrow the filters; decided before settlement, not charged).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal failure. The write may have completed; inspect before retrying.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "IDEMPOTENCY_UNAVAILABLE / TOOL_TIMEOUT / OVERLOADED. Inspect details.write_outcome: only not_started is safe to retry with the same key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/prompts/{prompt_id}/records": { "get": { "operationId": "listPromptRecords", "summary": "Monitoring records of one prompt", "description": "Paginated records, including pending and failed runs. At most 10,000 positions per query are reachable (page.capped); narrow the date window to continue. Cursors bind the brand, prompt, filters and limit. Pagination is not a snapshot: concurrent changes may skip or repeat records. Use explicit dates and deduplicate by id. Windows over 90 days use the long-window multiplier in x-geoly-cost. Billed per call at the price in x-geoly-cost, using the existing MCP credit meter. Billing outcomes are in meta.quota.", "tags": [ "Records" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "light", "base": 1, "unit": "call", "long_window_multiplier": 2, "guard_rpm": null }, "x-geoly-required-permission": "prompt:read", "x-geoly-pagination": { "style": "cursor", "max_position": 10000, "limit_param": "limit", "max_limit": 200, "cursor_param": "cursor", "next_cursor_path": "$.page.next_cursor" }, "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "cursor", "in": "parameters", "type": "cursor" } ], "outputs": { "nextCursor": "$.page.next_cursor" } }, "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "description": "Resource id for this API key brand.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512 } }, { "name": "time_range", "in": "query", "required": false, "schema": { "default": "30d", "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "description": "First business day; send with end_date (UTC+8 business day, YYYY-MM-DD).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "end_date", "in": "query", "required": false, "description": "Last business day inclusive; maximum 366 days (UTC+8 business day, YYYY-MM-DD).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "platform", "in": "query", "required": false, "schema": { "default": "all", "type": "string", "enum": [ "all", "chatgpt", "perplexity", "gemini", "google_ai", "copilot", "google_ai_overview" ] } }, { "name": "sort_order", "in": "query", "required": false, "description": "Record-day order. Offset pagination is not a snapshot; inserts or deletes can shift pages even in ascending order. Deduplicate by id.", "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Monitoring records of one prompt. `data` follows PromptRecordList when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptRecordListEnvelope" } } } }, "400": { "description": "INVALID_ARGUMENT (unknown query parameter, non-integer or out-of-range number, invalid enum value — details.errors[] lists each {param, reason, allowed?}) / INVALID_CURSOR (the cursor is malformed or belongs to another query — other filters or limit; drop it and start over) / FAILED_PRECONDITION (for example platform_not_enabled). Schema-level rejections are not charged; tool-level rejections retain their billing outcome in meta.quota.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no prompt with this prompt_id for the brand of this API key (details.reason = \"not_found\", details.resource = \"prompt\", details.id echoes the prompt_id). Billing follows meta.quota.charge.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/prompts/{prompt_id}/records/latest": { "get": { "operationId": "listLatestPromptRecords", "summary": "Latest monitoring record per platform", "description": "One latest record per platform, without a date filter. A valid prompt with no records returns an empty array. Billed per call at the price in x-geoly-cost, using the existing MCP credit meter. Billing outcomes are in meta.quota.", "tags": [ "Records" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "light", "base": 1, "unit": "call", "long_window_multiplier": null, "guard_rpm": null }, "x-geoly-required-permission": "prompt:read", "x-geoly-pagination": { "style": "none" }, "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "description": "Resource id for this API key brand.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "Latest monitoring record per platform. `data` follows LatestPromptRecordList when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestPromptRecordListEnvelope" } } } }, "400": { "description": "INVALID_ARGUMENT: a path parameter is out of range, or a query parameter was sent (this endpoint takes none) — details.errors[] lists each {param, reason}. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no prompt with this prompt_id for the brand of this API key (details.reason = \"not_found\", details.resource = \"prompt\", details.id echoes the prompt_id). Billing follows meta.quota.charge.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/records/{record_id}": { "get": { "operationId": "getRecord", "summary": "One monitoring record, optionally including its answer", "description": "Answer text is only returned when include=answer_text. Citations, search sources and shopping are bounded (30/30/20), with total counts and truncation flags. Internal provider errors and raw analysis are excluded. Responses exceeding 4 MB are rejected before settlement; omit include to fetch metadata. Billed per call at the price in x-geoly-cost, using the existing MCP credit meter. Billing outcomes are in meta.quota.", "tags": [ "Records" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "light", "base": 1, "unit": "call", "long_window_multiplier": null, "guard_rpm": null }, "x-geoly-required-permission": "prompt:read", "x-geoly-pagination": { "style": "none" }, "parameters": [ { "name": "record_id", "in": "path", "required": true, "description": "Resource id for this API key brand.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "include", "in": "query", "required": false, "description": "Return the full answer text; otherwise answer_text is null.", "schema": { "type": "string", "enum": [ "answer_text" ] } } ], "responses": { "200": { "description": "One monitoring record, optionally including its answer. `data` follows Record when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordEnvelope" } } } }, "400": { "description": "INVALID_ARGUMENT (unknown query parameter, non-integer or out-of-range number, invalid enum value — details.errors[] lists each {param, reason, allowed?}). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no record with this record_id for the brand of this API key (details.reason = \"not_found\", details.resource = \"record\", details.id echoes the record_id). Billing follows meta.quota.charge.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "RESPONSE_TOO_LARGE: response exceeds 4 MB; omit include=answer_text to retrieve metadata. Rejected before settlement.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/reports/prompt-overview": { "post": { "operationId": "runPromptOverviewReport", "summary": "Window overview of one prompt", "description": "caliber and kpi_state distinguish legacy, mention-based and unavailable KPIs; with kpi_state own_pending the brand mention counts, rates and rank are null rather than placeholder zeros. Rates use percentages without conversion. Custom windows over 90 days are clamped by the tool; window echoes the actual interval. Source domains include the first page and total counts. GET with body payload — no resources created. Billed per call at the price in x-geoly-cost (the same as the matching GEOly MCP tool).", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "light", "base": 1, "unit": "call", "long_window_multiplier": null, "guard_rpm": null }, "x-geoly-required-permission": "prompt:read", "x-geoly-pagination": { "style": "none" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPromptOverviewReportRequest" } } } }, "responses": { "200": { "description": "The prompt-overview report. `data` follows PromptOverviewReport when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptOverviewReportEnvelope" } } } }, "400": { "description": "INVALID_BODY / INVALID_ARGUMENT (unknown field, wrong type, invalid enum value, missing required field — details.errors[] lists each {param, reason, allowed?}; or an argument the report could only reject after looking it up) / INVALID_CURSOR (the cursor belongs to another query — drop it and start over) / FAILED_PRECONDITION (details.reason: platform_not_enabled, locale_required, request_rejected). Schema-level rejections are not charged; see meta.quota for the rest.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_NOT_FOUND (unknown report name; not charged) / NOT_FOUND (a referenced id does not exist for this brand; billing in meta.quota.charge).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE: request body exceeds 64 KB.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send the body as application/json.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "QUERY_TOO_EXPENSIVE (narrow the window / filters) / RESPONSE_TOO_LARGE (the response exceeds 4 MB — lower limit or narrow the filters; decided before settlement, not charged).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/quota": { "get": { "operationId": "getQuota", "summary": "Credit balance of this API key's organization", "description": "MCP credits (the pool Data API calls are billed against) and AI credits of the organization that owns this API key: limit, used, remaining and reset time. Free; no query parameters.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "free", "base": 0, "unit": null, "long_window_multiplier": null, "guard_rpm": null }, "x-geoly-required-permission": null, "x-geoly-pagination": { "style": "none" }, "responses": { "200": { "description": "The quota report. `data` follows QuotaReport when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaReportEnvelope" } } } }, "400": { "description": "INVALID_ARGUMENT: this endpoint takes no query parameters.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/brand": { "get": { "operationId": "getBrand", "summary": "The brand this API key is bound to", "description": "Brand profile, owning organization (plan, subscription status), AI platforms with completed answers in the last 30 days (entitled = covered by the plan), the first / last record day and first-collection progress. Use it to check which brand a key reads. Record days are UTC record-day keys (*_utc_date = business day − 1). Free; no query parameters.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "free", "base": 0, "unit": null, "long_window_multiplier": null, "guard_rpm": null }, "x-geoly-required-permission": "brand:read", "x-geoly-pagination": { "style": "none" }, "responses": { "200": { "description": "The brand this API key is bound to. `data` follows Brand when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandEnvelope" } } } }, "400": { "description": "INVALID_ARGUMENT: this endpoint takes no query parameters.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/topics": { "get": { "operationId": "listTopics", "summary": "Topics of the brand (all, unpaginated)", "description": "Every monitored topic of the brand with its active and archived prompt counts — the left rail of the in-app /prompts page. A small set, returned whole (no pagination). Prompts without a topic are not a row here: count them with GET /api/v1/prompts?topic_id=_none (page.total). Free; no query parameters.", "tags": [ "Catalog" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "free", "base": 0, "unit": null, "long_window_multiplier": null, "guard_rpm": null }, "x-geoly-required-permission": null, "x-geoly-pagination": { "style": "none" }, "responses": { "200": { "description": "Topics of the brand (all, unpaginated). `data` follows TopicList when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicListEnvelope" } } } }, "400": { "description": "INVALID_ARGUMENT: this endpoint takes no query parameters.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/prompts/{prompt_id}": { "get": { "operationId": "getPrompt", "summary": "One prompt of the brand", "description": "A single prompt by id, active or archived — the same row shape as GET /api/v1/prompts. 404 NOT_FOUND when the id does not exist for this key's brand. Free (no credits); no metrics are computed. Guarded at 200 requests per minute per organization: one bucket for GET /api/v1/prompts, GET /api/v1/prompts/{prompt_id} and the same organization's get_prompt_list view=catalog calls on the GEOly MCP / Agent API — separate from the prompts report's bucket.", "tags": [ "Catalog" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "free", "base": 0, "unit": null, "long_window_multiplier": null, "guard_rpm": 200 }, "x-geoly-required-permission": "prompt:read", "x-geoly-pagination": { "style": "none" }, "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "description": "Prompt id (the `id` of a row from GET /api/v1/prompts).", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "One prompt of the brand. `data` follows Prompt when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptEnvelope" } } } }, "400": { "description": "INVALID_ARGUMENT: a path parameter is out of range, or a query parameter was sent (this endpoint takes none) — details.errors[] lists each {param, reason}. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: no prompt with this prompt_id for the brand of this API key (details.reason = \"not_found\", details.resource = \"prompt\", details.id echoes the prompt_id). Billing follows meta.quota.charge.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/reports/overview": { "post": { "operationId": "runOverviewReport", "summary": "Brand visibility overview (the /performance headline)", "description": "Visibility score, mention rate, citation rate, share of voice and the per-platform breakdown for the window — the same numbers as the in-app overview. Every number counts the brands you track (your own brand + the competitors you added) under the current configuration; rank is among tracked brands only. data.kpi_state tells whether the KPIs are computed (ok), there are no counted answers in the window (no_data), the first count is still running (computing — no numbers yet, not 0), or the filtered read failed (unavailable). GET with body payload — no resources created. Billed per call at the price in x-geoly-cost (the same as the matching GEOly MCP tool).", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "standard", "base": 3, "unit": "call", "long_window_multiplier": null, "guard_rpm": 20 }, "x-geoly-required-permission": "brand:read", "x-geoly-pagination": { "style": "none" }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunOverviewReportRequest" } } } }, "responses": { "200": { "description": "The overview report. `data` follows OverviewReport when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverviewReportEnvelope" } } } }, "400": { "description": "INVALID_BODY / INVALID_ARGUMENT (unknown field, wrong type, invalid enum value, missing required field — details.errors[] lists each {param, reason, allowed?}; or an argument the report could only reject after looking it up) / INVALID_CURSOR (the cursor belongs to another query — drop it and start over) / FAILED_PRECONDITION (details.reason: platform_not_enabled, locale_required, request_rejected). Schema-level rejections are not charged; see meta.quota for the rest.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_NOT_FOUND (unknown report name; not charged) / NOT_FOUND (a referenced id does not exist for this brand; billing in meta.quota.charge).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE: request body exceeds 64 KB.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send the body as application/json.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "QUERY_TOO_EXPENSIVE (narrow the window / filters) / RESPONSE_TOO_LARGE (the response exceeds 4 MB — lower limit or narrow the filters; decided before settlement, not charged).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/reports/analytics": { "post": { "operationId": "runAnalyticsReport", "summary": "Daily visibility metrics by platform / total / topic", "description": "Fixed columns per day (completed / mentioned answers, mention and citation rates, visibility score, sentiment buckets), optionally with the previous equal-length window. Rows carry both utc_date and business_date. Very long windows with breakdown=platform or topic may be capped (data.capped is then non-null and says what was kept). GET with body payload — no resources created. Billed per call at the price in x-geoly-cost (the same as the matching GEOly MCP tool).", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "light", "base": 1, "unit": "call", "long_window_multiplier": null, "guard_rpm": 30 }, "x-geoly-required-permission": "analytics:read", "x-geoly-pagination": { "style": "none" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAnalyticsReportRequest" } } } }, "responses": { "200": { "description": "The analytics report. `data` follows AnalyticsReport when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsReportEnvelope" } } } }, "400": { "description": "INVALID_BODY / INVALID_ARGUMENT (unknown field, wrong type, invalid enum value, missing required field — details.errors[] lists each {param, reason, allowed?}; or an argument the report could only reject after looking it up) / INVALID_CURSOR (the cursor belongs to another query — drop it and start over) / FAILED_PRECONDITION (details.reason: platform_not_enabled, locale_required, request_rejected). Schema-level rejections are not charged; see meta.quota for the rest.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_NOT_FOUND (unknown report name; not charged) / NOT_FOUND (a referenced id does not exist for this brand; billing in meta.quota.charge).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE: request body exceeds 64 KB.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send the body as application/json.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "QUERY_TOO_EXPENSIVE (narrow the window / filters) / RESPONSE_TOO_LARGE (the response exceeds 4 MB — lower limit or narrow the filters; decided before settlement, not charged).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/reports/brand-board": { "post": { "operationId": "runBrandBoardReport", "summary": "Brand leaderboard (who AI answers mention, and how often)", "description": "Your brand and the competitors you track, ranked by mention rate in the window (caliber \"tracked_brand_v1\"; untracked brands never appear, rank is among tracked brands only). data.mode is \"confirmed\" for every filter combination (\"scoped_open_world\" is no longer returned); data.status says whether the board is ready (not_ready while the brand's first count is still running). GET with body payload — no resources created. Billed per call at the price in x-geoly-cost (the same as the matching GEOly MCP tool).", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "standard", "base": 3, "unit": "call", "long_window_multiplier": 2, "guard_rpm": null }, "x-geoly-required-permission": "competitor:read", "x-geoly-pagination": { "style": "top_n", "limit_param": "limit", "max_limit": 50 }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunBrandBoardReportRequest" } } } }, "responses": { "200": { "description": "The brand-board report. `data` follows BrandBoardReport when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandBoardReportEnvelope" } } } }, "400": { "description": "INVALID_BODY / INVALID_ARGUMENT (unknown field, wrong type, invalid enum value, missing required field — details.errors[] lists each {param, reason, allowed?}; or an argument the report could only reject after looking it up) / INVALID_CURSOR (the cursor belongs to another query — drop it and start over) / FAILED_PRECONDITION (details.reason: platform_not_enabled, locale_required, request_rejected). Schema-level rejections are not charged; see meta.quota for the rest.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_NOT_FOUND (unknown report name; not charged) / NOT_FOUND (a referenced id does not exist for this brand; billing in meta.quota.charge).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE: request body exceeds 64 KB.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send the body as application/json.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "QUERY_TOO_EXPENSIVE (narrow the window / filters) / RESPONSE_TOO_LARGE (the response exceeds 4 MB — lower limit or narrow the filters; decided before settlement, not charged).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/reports/citations": { "post": { "operationId": "runCitationsReport", "summary": "Citation source board (which domains AI answers cite)", "description": "Top cited root domains with movers, your share, citation type split and the daily trend over closed business days. With a topic filter the whole-brand stats block is null and data.filtered is true. GET with body payload — no resources created. Billed per call at the price in x-geoly-cost (the same as the matching GEOly MCP tool).", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "deep", "base": 10, "unit": "call", "long_window_multiplier": null, "guard_rpm": 20 }, "x-geoly-required-permission": "citation:read", "x-geoly-pagination": { "style": "none" }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCitationsReportRequest" } } } }, "responses": { "200": { "description": "The citations report. `data` follows CitationsReport when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CitationsReportEnvelope" } } } }, "400": { "description": "INVALID_BODY / INVALID_ARGUMENT (unknown field, wrong type, invalid enum value, missing required field — details.errors[] lists each {param, reason, allowed?}; or an argument the report could only reject after looking it up) / INVALID_CURSOR (the cursor belongs to another query — drop it and start over) / FAILED_PRECONDITION (details.reason: platform_not_enabled, locale_required, request_rejected). Schema-level rejections are not charged; see meta.quota for the rest.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_NOT_FOUND (unknown report name; not charged) / NOT_FOUND (a referenced id does not exist for this brand; billing in meta.quota.charge).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE: request body exceeds 64 KB.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send the body as application/json.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "QUERY_TOO_EXPENSIVE (narrow the window / filters) / RESPONSE_TOO_LARGE (the response exceeds 4 MB — lower limit or narrow the filters; decided before settlement, not charged).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/reports/prompts": { "post": { "operationId": "runPromptsReport", "summary": "Prompt table with per-prompt metrics (paginated)", "description": "The in-app prompts table: per-prompt visibility, mention rate, citation rate, latest record per platform and window-over-window deltas, plus a summary of the whole filtered set. Paginate with cursor until page.next_cursor is null; the same filters and limit must be sent with every page. GET with body payload — no resources created. Billed per call at the price in x-geoly-cost (the same as the matching GEOly MCP tool).", "tags": [ "Reports" ], "security": [ { "bearerAuth": [] } ], "x-geoly-stability": "stable", "x-geoly-cost": { "tier": "standard", "base": 3, "unit": "call", "long_window_multiplier": null, "guard_rpm": 200 }, "x-geoly-required-permission": "prompt:read", "x-geoly-pagination": { "style": "cursor", "limit_param": "limit", "max_limit": 100, "cursor_param": "cursor", "next_cursor_path": "$.page.next_cursor" }, "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "cursor", "in": "requestBody", "type": "cursor" } ], "outputs": { "nextCursor": "$.page.next_cursor" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPromptsReportRequest" } } } }, "responses": { "200": { "description": "The prompts report. `data` follows PromptsReport when meta.schema_conformant is true.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptsReportEnvelope" } } } }, "400": { "description": "INVALID_BODY / INVALID_ARGUMENT (unknown field, wrong type, invalid enum value, missing required field — details.errors[] lists each {param, reason, allowed?}; or an argument the report could only reject after looking it up) / INVALID_CURSOR (the cursor belongs to another query — drop it and start over) / FAILED_PRECONDITION (details.reason: platform_not_enabled, locale_required, request_rejected). Schema-level rejections are not charged; see meta.quota for the rest.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "UNAUTHORIZED: missing or invalid API key.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "QUOTA_EXCEEDED / SUBSCRIPTION_INACTIVE / ORG_NOT_ELIGIBLE. Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API_KEY_BRAND_REQUIRED (the key is not bound to a brand) / PERMISSION_DENIED (the key lacks the read permission in x-geoly-required-permission; details.required names it). Not charged.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_NOT_FOUND (unknown report name; not charged) / NOT_FOUND (a referenced id does not exist for this brand; billing in meta.quota.charge).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE: request body exceeds 64 KB.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send the body as application/json.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "QUERY_TOO_EXPENSIVE (narrow the window / filters) / RESPONSE_TOO_LARGE (the response exceeds 4 MB — lower limit or narrow the filters; decided before settlement, not charged).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED / GUARDED_RATE_LIMITED / BUSY / BUDGET_EXCEEDED. Not charged; honor Retry-After and pace with X-DB-Budget-*.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: unexpected server error (not charged). Retry once with backoff; report the Request-Id if it persists.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TOOL_TIMEOUT / OVERLOADED / CIRCUIT_OPEN / TOOL_FAILED. Not charged; retry later, honoring Retry-After when present. (502 / 504 are never used.)", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "GEOly-API-Version": { "$ref": "#/components/headers/GEOly-API-Version" }, "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-DB-Budget-Limit": { "$ref": "#/components/headers/X-DB-Budget-Limit" }, "X-DB-Budget-Used": { "$ref": "#/components/headers/X-DB-Budget-Used" }, "X-DB-Budget-Reset": { "$ref": "#/components/headers/X-DB-Budget-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from Settings → Developer → API keys (prefix geom_). Each key is bound to one brand." } }, "headers": { "Request-Id": { "description": "Unique id of this request (equals meta.request_id). Include it when reporting a problem.", "schema": { "type": "string" } }, "GEOly-API-Version": { "description": "API contract version. Always \"1\" on /api/v1.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requests allowed per credential in the current one-minute window. Sent on every response after the API key has been authenticated; absent on errors raised while authenticating (401) and on 405.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the current window resets (0–60).", "schema": { "type": "integer" } }, "X-DB-Budget-Limit": { "description": "Organization database-seconds budget per rolling 60 minutes. Sent on every response after authentication.", "schema": { "type": "integer" } }, "X-DB-Budget-Used": { "description": "Database seconds used by the organization in the last 60 minutes.", "schema": { "type": "integer" } }, "X-DB-Budget-Reset": { "description": "Seconds until the oldest usage bucket expires.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying (429; 503 when retryable).", "schema": { "type": "integer" } }, "Allow": { "description": "Methods supported on this path (405 responses).", "schema": { "type": "string" } } }, "schemas": { "RecordFeed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt_id": { "type": "string" }, "prompt_text": { "type": "string" }, "platform_code": { "type": [ "string", "null" ] }, "platform_name": { "type": [ "string", "null" ] }, "record_date_at": { "type": "string", "format": "date-time" }, "business_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "changed_at": { "description": "Update position of this record (prompt_record.updated_at, microseconds). The feed orders by changed_at then id; upsert by id.", "type": "string", "format": "date-time" }, "status": { "type": "string", "const": "completed" }, "mentions": { "type": [ "integer", "null" ] }, "mention_rank": { "type": [ "integer", "null" ], "description": "Read-time value. Rank backfills do not advance changed_at, so this can change while changed_at stays the same and the feed will not re-emit the record for it. To reconcile, poll again from an updated_since rewound by an overlap of at least 24 hours, or re-read records by record date." }, "sentiment": { "type": [ "string", "null" ] }, "sentiment_polarity": { "type": [ "number", "null" ] }, "answer_text": { "type": [ "string", "null" ] }, "citations": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string" }, "source_type": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "position": { "type": [ "integer", "null" ] } }, "required": [ "id", "source_type", "url", "domain", "title", "position" ], "additionalProperties": {} }, "description": "Requested with include=citations: up to 30 per record, ordered by position (nulls last) then id — the same order and cut as GET /api/v1/records/{record_id}. citations_truncated flags a cut." }, "citations_truncated": { "type": [ "boolean", "null" ] } }, "required": [ "id", "prompt_id", "prompt_text", "platform_code", "platform_name", "record_date_at", "business_date", "changed_at", "status", "mentions", "mention_rank", "sentiment", "sentiment_polarity", "answer_text", "citations", "citations_truncated" ], "additionalProperties": {} } }, "RecordFeedEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/RecordFeed" }, { "type": "null" } ], "description": "Incremental completed records and subsequent changes. null only when meta.schema_conformant is false and the output could not be mapped." }, "page": { "$ref": "#/components/schemas/FeedPage" }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "page", "meta" ] }, "CreatePromptRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 10000 }, "category": { "type": "string", "maxLength": 128 }, "priority": { "type": "string", "maxLength": 64 }, "country": { "default": "US", "type": "string", "minLength": 2, "maxLength": 2 }, "topic_id": { "description": "Resource id for this API key brand.", "type": "string", "minLength": 1, "maxLength": 64 }, "tags": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "required": [ "text" ], "additionalProperties": false }, "CreatedPrompt": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "country": { "type": "string" }, "topic_id": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tags read back after creation; null when they could not be read back." }, "tags_state": { "description": "[Extensible enum] saved = every requested tag was read back; partial = the prompt was created but at least one requested tag was not saved; unavailable = the saved tags could not be confirmed. The prompt exists in all three cases: never create it again because of this field. Known values: \"saved\", \"partial\", \"unavailable\"; more may be added.", "type": "string", "examples": [ "saved", "partial", "unavailable" ] }, "tags_warning": { "type": [ "string", "null" ], "description": "Why tags_state is not saved; null when it is saved." } }, "required": [ "id", "text", "country", "topic_id", "is_active", "created_at", "tags", "tags_state", "tags_warning" ], "additionalProperties": {} }, "CreatedPromptEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/CreatedPrompt" }, { "type": "null" } ], "description": "Create a monitoring prompt. null only when meta.schema_conformant is false and the output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "CreatePromptRunRequest": { "type": "object", "properties": {}, "additionalProperties": false }, "PromptRun": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "records_created": { "type": "integer", "minimum": 0 }, "dispatched": { "type": "integer", "minimum": 0 }, "business_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "prompt_id", "records_created", "dispatched", "business_date" ], "additionalProperties": {} }, "PromptRunEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/PromptRun" }, { "type": "null" } ], "description": "Trigger monitoring for a prompt. null only when meta.schema_conformant is false and the output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "PromptRecordList": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "record_date_at": { "type": "string", "format": "date-time" }, "business_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "status": { "type": "string", "examples": [ "pending", "running", "completed", "failed", "timeout", "cancelled", "skipped" ], "description": "[Extensible enum] Known values: \"pending\", \"running\", \"completed\", \"failed\", \"timeout\", \"cancelled\", \"skipped\"; more may be added." }, "position": { "type": [ "integer", "null" ] }, "mention_rank": { "type": [ "integer", "null" ] }, "mentions": { "type": [ "integer", "null" ], "minimum": 0 }, "sentiment": { "type": [ "string", "null" ], "examples": [ "positive", "neutral", "negative", "mixed" ], "description": "[Extensible enum] Known values: \"positive\", \"neutral\", \"negative\", \"mixed\"; more may be added." }, "sentiment_polarity": { "type": [ "number", "null" ], "minimum": -1, "maximum": 1 }, "shopping_visible": { "type": [ "boolean", "null" ] } }, "required": [ "id", "platform_code", "platform_name", "record_date_at", "business_date", "status", "position", "mention_rank", "mentions", "sentiment", "sentiment_polarity", "shopping_visible" ], "additionalProperties": {} } }, "PromptRecordListEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/PromptRecordList" }, { "type": "null" } ], "description": "Monitoring records of one prompt. null only when meta.schema_conformant is false and the output could not be mapped." }, "page": { "$ref": "#/components/schemas/CursorPage" }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "page", "meta" ] }, "LatestPromptRecordList": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "record_date_at": { "type": "string", "format": "date-time" }, "business_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "status": { "type": "string", "examples": [ "pending", "running", "completed", "failed", "timeout", "cancelled", "skipped" ], "description": "[Extensible enum] Known values: \"pending\", \"running\", \"completed\", \"failed\", \"timeout\", \"cancelled\", \"skipped\"; more may be added." }, "position": { "type": [ "integer", "null" ] }, "mention_rank": { "type": [ "integer", "null" ] }, "mentions": { "type": [ "integer", "null" ], "minimum": 0 }, "sentiment": { "type": [ "string", "null" ], "examples": [ "positive", "neutral", "negative", "mixed" ], "description": "[Extensible enum] Known values: \"positive\", \"neutral\", \"negative\", \"mixed\"; more may be added." }, "sentiment_polarity": { "type": [ "number", "null" ], "minimum": -1, "maximum": 1 } }, "required": [ "id", "platform_code", "platform_name", "record_date_at", "business_date", "status", "position", "mention_rank", "mentions", "sentiment", "sentiment_polarity" ], "additionalProperties": {} } }, "LatestPromptRecordListEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/LatestPromptRecordList" }, { "type": "null" } ], "description": "Latest monitoring record per platform. null only when meta.schema_conformant is false and the output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "Record": { "type": "object", "properties": { "id": { "type": "string" }, "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "record_date_at": { "type": "string", "format": "date-time" }, "business_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "status": { "type": "string", "examples": [ "pending", "running", "completed", "failed", "timeout", "cancelled", "skipped" ], "description": "[Extensible enum] Known values: \"pending\", \"running\", \"completed\", \"failed\", \"timeout\", \"cancelled\", \"skipped\"; more may be added." }, "position": { "type": [ "integer", "null" ] }, "mention_rank": { "type": [ "integer", "null" ] }, "mentions": { "type": [ "integer", "null" ], "minimum": 0 }, "sentiment": { "type": [ "string", "null" ], "examples": [ "positive", "neutral", "negative", "mixed" ], "description": "[Extensible enum] Known values: \"positive\", \"neutral\", \"negative\", \"mixed\"; more may be added." }, "sentiment_polarity": { "type": [ "number", "null" ], "minimum": -1, "maximum": 1 }, "prompt_id": { "type": "string" }, "prompt_text": { "type": "string" }, "in_flight": { "type": "boolean" }, "executed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "ai_model": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "sentiment_highlights": { "type": [ "array", "null" ], "items": { "type": "string" } }, "displayed": { "type": "object", "properties": { "sentiment": { "type": [ "string", "null" ], "examples": [ "positive", "neutral", "negative", "mixed" ], "description": "[Extensible enum] Known values: \"positive\", \"neutral\", \"negative\", \"mixed\"; more may be added." }, "mention_rank": { "type": [ "integer", "null" ] } }, "required": [ "sentiment", "mention_rank" ], "additionalProperties": {} }, "web_search_status": { "type": "string", "examples": [ "searched", "not_searched", "unknown" ], "description": "[Extensible enum] Known values: \"searched\", \"not_searched\", \"unknown\"; more may be added." }, "search_queries": { "type": "array", "items": { "type": "string" } }, "related_prompts": { "type": [ "array", "null" ], "items": { "type": "string" } }, "shopping_visible": { "type": [ "boolean", "null" ] }, "ai_overview_triggered": { "type": [ "boolean", "null" ] }, "answer_text": { "type": [ "string", "null" ] }, "answer_text_state": { "type": "string", "examples": [ "included", "not_requested", "empty" ], "description": "[Extensible enum] Known values: \"included\", \"not_requested\", \"empty\"; more may be added." }, "citations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source_type": { "type": "string", "examples": [ "citation", "link_attached", "source_chip" ], "description": "[Extensible enum] Known values: \"citation\", \"link_attached\", \"source_chip\"; more may be added." }, "url": { "type": [ "string", "null" ] }, "site_name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "position": { "type": [ "integer", "null" ] }, "cited": { "type": [ "boolean", "null" ] }, "description": { "type": [ "string", "null" ] }, "link_text": { "type": [ "string", "null" ] }, "marker_positions": { "type": "array", "items": { "type": "integer" } }, "is_brand_mention": { "type": "boolean" } }, "required": [ "id", "source_type", "url", "site_name", "domain", "title", "position", "cited", "description", "link_text", "marker_positions", "is_brand_mention" ], "additionalProperties": {} } }, "total_citations": { "type": "integer", "minimum": 0 }, "citations_truncated": { "type": "boolean" }, "search_sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "rank": { "type": [ "integer", "null" ] }, "url": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "snippet": { "type": [ "string", "null" ] }, "published": { "type": [ "string", "null" ] } }, "required": [ "id", "rank", "url", "title", "snippet", "published" ], "additionalProperties": {} } }, "total_search_sources": { "type": "integer", "minimum": 0 }, "search_sources_truncated": { "type": "boolean" }, "shopping": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "rating": { "type": [ "number", "null" ] }, "reviews": { "type": [ "integer", "null" ], "minimum": 0 }, "link": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "seller": { "type": [ "string", "null" ] }, "final_price": { "type": [ "number", "null" ] }, "price_currency": { "type": [ "string", "null" ] }, "tag": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "rating", "reviews", "link", "image_url", "seller", "final_price", "price_currency", "tag" ], "additionalProperties": {} } }, "total_shopping": { "type": "integer", "minimum": 0 }, "shopping_truncated": { "type": "boolean" }, "mentioned_brands": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "entity_id": { "type": [ "string", "null" ], "description": "Brand-entity id, the same id the brand-board report uses. null when source is legacy." }, "source": { "description": "[Extensible enum] entity = the brand-entity layer. legacy = fallback for an answer that has no entity rows yet: the brand comes from the older mentioned-brands table, with no entity id, no mention count and no role. Known values: \"entity\", \"legacy\"; more may be added.", "type": "string", "examples": [ "entity", "legacy" ] }, "name": { "type": "string" }, "is_own_brand": { "type": "boolean" }, "role": { "type": [ "string", "null" ] }, "stance": { "type": [ "string", "null" ], "examples": [ "preferred", "equal", "inferior", "we_absent" ], "description": "[Extensible enum] Known values: \"preferred\", \"equal\", \"inferior\", \"we_absent\"; more may be added." }, "stance_source": { "type": [ "string", "null" ], "examples": [ "vote", "prmb" ], "description": "[Extensible enum] Known values: \"vote\", \"prmb\"; more may be added." }, "mention_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Mentions of this brand in the answer. null when source is legacy (the fallback table has no count)." }, "domain": { "type": [ "string", "null" ] } }, "required": [ "entity_id", "source", "name", "is_own_brand", "role", "stance", "stance_source", "mention_count", "domain" ], "additionalProperties": {} } }, "mentioned_brands_state": { "type": "string", "examples": [ "ok", "unavailable" ], "description": "[Extensible enum] Known values: \"ok\", \"unavailable\"; more may be added." } }, "required": [ "id", "platform_code", "platform_name", "record_date_at", "business_date", "status", "position", "mention_rank", "mentions", "sentiment", "sentiment_polarity", "prompt_id", "prompt_text", "in_flight", "executed_at", "created_at", "updated_at", "ai_model", "country", "sentiment_highlights", "displayed", "web_search_status", "search_queries", "related_prompts", "shopping_visible", "ai_overview_triggered", "answer_text", "answer_text_state", "citations", "total_citations", "citations_truncated", "search_sources", "total_search_sources", "search_sources_truncated", "shopping", "total_shopping", "shopping_truncated", "mentioned_brands", "mentioned_brands_state" ], "additionalProperties": {} }, "RecordEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/Record" }, { "type": "null" } ], "description": "One monitoring record, optionally including its answer. null only when meta.schema_conformant is false and the output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "RunPromptOverviewReportRequest": { "type": "object", "properties": { "prompt_id": { "description": "Resource id for this API key brand.", "type": "string", "minLength": 1, "maxLength": 64 }, "time_range": { "default": "30d", "type": "string", "enum": [ "7d", "30d", "custom" ] }, "start_date": { "description": "Start of a custom window (UTC+8 business day, YYYY-MM-DD).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "description": "End of a custom window (UTC+8 business day, YYYY-MM-DD).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "platform": { "default": "all", "type": "string", "enum": [ "all", "chatgpt", "perplexity", "gemini", "google_ai", "copilot", "google_ai_overview" ] } }, "required": [ "prompt_id" ], "additionalProperties": false }, "PromptOverviewReport": { "type": "object", "properties": { "prompt": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "topic_id": { "type": [ "string", "null" ] }, "topic_name": { "type": [ "string", "null" ] }, "is_branded": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "text", "country", "is_active", "topic_id", "topic_name", "is_branded", "created_at" ], "additionalProperties": {} }, "platform": { "type": "string" }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "custom" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"custom\"; more may be added." }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": [ "string", "null" ], "format": "date-time" }, "end_bounded": { "type": "boolean" } }, "required": [ "time_range", "start_at", "end_at", "end_bounded" ], "additionalProperties": {} }, "caliber": { "type": "string", "examples": [ "legacy", "mention" ], "description": "[Extensible enum] Known values: \"legacy\", \"mention\"; more may be added." }, "kpi_state": { "type": "string", "examples": [ "ok", "no_data", "own_pending" ], "description": "[Extensible enum] Known values: \"ok\", \"no_data\", \"own_pending\"; more may be added." }, "brand": { "type": "object", "properties": { "completed_records": { "type": "integer", "minimum": 0 }, "mentioned_records": { "type": [ "integer", "null" ], "minimum": 0, "description": "Answers in the window that mention your brand. null when kpi_state is own_pending: your brand entity is not set up yet, so there is no count." }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "mentioned_records / completed_records in percent. null when kpi_state is no_data or own_pending." }, "visibility_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "share_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "rank": { "type": [ "integer", "null" ], "minimum": 1, "description": "Your position among the brands of the window, the same rank the app shows. With caliber mention it is ranked against every confirmed competitor and is null when every brand scores 0; with caliber legacy it is a lower bound when competitor_board.total_rows exceeds the rows shown. null when kpi_state is no_data or own_pending." } }, "required": [ "completed_records", "mentioned_records", "mention_rate_pct", "visibility_score", "share_pct", "rank" ], "additionalProperties": {} }, "top_competitor": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "mention_rate_pct": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "name", "mention_rate_pct" ], "additionalProperties": {} }, "competitor_board": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "visibility_score": { "type": "number", "minimum": 0, "maximum": 100 }, "share_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "name", "visibility_score", "share_pct" ], "additionalProperties": {} } }, "total_rows": { "type": "integer", "minimum": 0 }, "discovered_competitors": { "type": "integer", "minimum": 0 } }, "required": [ "rows", "total_rows", "discovered_competitors" ], "additionalProperties": {} }, "platform_matrix": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "completed_records": { "type": "integer", "minimum": 0 }, "filterable": { "type": "boolean" } }, "required": [ "platform_code", "platform_name", "completed_records", "filterable" ], "additionalProperties": {} } }, "brand_mention_rate_pct": { "type": [ "array", "null" ], "items": { "type": "number", "minimum": 0, "maximum": 100 }, "description": "Your mention rate per column, in column order. null when kpi_state is own_pending." }, "competitors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "mention_rate_pct": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 100 } } }, "required": [ "name", "mention_rate_pct" ], "additionalProperties": {} } } }, "required": [ "columns", "brand_mention_rate_pct", "competitors" ], "additionalProperties": {} }, "source_domains": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "ready", "unavailable", "computing" ], "description": "[Extensible enum] Known values: \"ready\", \"unavailable\", \"computing\"; more may be added." }, "rows": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 } }, "required": [ "domain", "citations" ], "additionalProperties": {} } }, "total_domains": { "type": "integer", "minimum": 0 }, "citations_by_owner": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "brand": { "type": "integer", "minimum": 0 }, "competitor": { "type": "integer", "minimum": 0 }, "other": { "type": "integer", "minimum": 0 } }, "required": [ "total", "brand", "competitor", "other" ], "additionalProperties": {} }, "own_domains": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "rows", "total_domains", "citations_by_owner", "own_domains" ], "additionalProperties": {} }, "coverage": { "type": [ "object", "null" ], "properties": { "floor_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "clamped": { "type": "boolean" } }, "required": [ "floor_date", "clamped" ], "additionalProperties": {} } }, "required": [ "prompt", "platform", "window", "caliber", "kpi_state", "brand", "top_competitor", "competitor_board", "platform_matrix", "source_domains", "coverage" ], "additionalProperties": {} }, "PromptOverviewReportEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/PromptOverviewReport" }, { "type": "null" } ], "description": "The prompt-overview report. null only when meta.schema_conformant is false and the report output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "QuotaReport": { "oneOf": [ { "type": "object", "properties": { "org_id": { "type": "string" }, "status": { "type": "string", "const": "available" }, "plan": { "type": "string" }, "mcp_credits": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "minimum": 0 }, "unlimited": { "type": "boolean" }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": [ "integer", "null" ] }, "resets_at": { "type": "string", "format": "date-time" }, "period_start_at": { "type": "string", "format": "date-time" } }, "required": [ "limit", "unlimited", "used", "remaining", "resets_at", "period_start_at" ], "additionalProperties": {} }, "ai_credits": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "available" }, "limit": { "type": [ "integer", "null" ], "minimum": 0 }, "unlimited": { "type": "boolean" }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": [ "integer", "null" ] }, "resets_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "limit", "unlimited", "used", "remaining", "resets_at" ], "additionalProperties": {} }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable" }, "limit": { "type": "null" }, "unlimited": { "type": "null" }, "used": { "type": "null" }, "remaining": { "type": "null" }, "resets_at": { "type": "null" } }, "required": [ "status", "limit", "unlimited", "used", "remaining", "resets_at" ], "additionalProperties": {} } ] }, "rate_version": { "type": "string" } }, "required": [ "org_id", "status", "plan", "mcp_credits", "ai_credits", "rate_version" ], "additionalProperties": {} }, { "type": "object", "properties": { "org_id": { "type": "string" }, "status": { "type": "string", "const": "unavailable" }, "plan": { "type": "null" }, "mcp_credits": { "type": "null" }, "ai_credits": { "type": "null" }, "rate_version": { "type": "string" } }, "required": [ "org_id", "status", "plan", "mcp_credits", "ai_credits", "rate_version" ], "additionalProperties": {} } ] }, "QuotaReportEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/QuotaReport" }, { "type": "null" } ], "description": "The quota report. null only when meta.schema_conformant is false and the report output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "Brand": { "type": "object", "properties": { "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "website": { "type": "string" }, "industry": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "domain", "website", "industry", "description", "logo_url" ], "additionalProperties": {} }, "organization": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": [ "string", "null" ] }, "subscription_status": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "plan", "subscription_status" ], "additionalProperties": {} }, "platforms": { "type": "object", "properties": { "window": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 0 }, "start_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "days", "start_utc_date", "end_utc_date" ], "additionalProperties": {} }, "rows": { "type": "array", "items": { "type": "object", "properties": { "platform_code": { "type": "string" }, "name": { "type": "string" }, "entitled": { "type": "boolean" }, "last_utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "completed_records": { "type": "integer", "minimum": 0 } }, "required": [ "platform_code", "name", "entitled", "last_utc_date", "completed_records" ], "additionalProperties": {} } } }, "required": [ "window", "rows" ], "additionalProperties": {} }, "data_window": { "type": "object", "properties": { "first_utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "last_utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "first_utc_date", "last_utc_date" ], "additionalProperties": {} }, "first_run": { "type": "object", "properties": { "phase": { "type": "string", "examples": [ "collecting", "failed", "ready", "none", "unavailable" ], "description": "[Extensible enum] Known values: \"collecting\", \"failed\", \"ready\", \"none\", \"unavailable\"; more may be added." }, "progress": { "type": [ "object", "null" ], "properties": { "completed_records": { "type": "integer", "minimum": 0 }, "in_flight_records": { "type": "integer", "minimum": 0 }, "failed_records": { "type": "integer", "minimum": 0 }, "total_records": { "type": "integer", "minimum": 0 }, "mentioned_records": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "completed_records", "in_flight_records", "failed_records", "total_records", "mentioned_records" ], "additionalProperties": {} } }, "required": [ "phase", "progress" ], "additionalProperties": {} } }, "required": [ "brand", "organization", "platforms", "data_window", "first_run" ], "additionalProperties": {} }, "BrandEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/Brand" }, { "type": "null" } ], "description": "The brand this API key is bound to. null only when meta.schema_conformant is false and the output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "TopicList": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "position": { "type": "integer" }, "active_prompt_count": { "type": "integer", "minimum": 0 }, "archived_prompt_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "position", "active_prompt_count", "archived_prompt_count", "created_at", "updated_at" ], "additionalProperties": {} } }, "TopicListEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/TopicList" }, { "type": "null" } ], "description": "Topics of the brand (all, unpaginated). null only when meta.schema_conformant is false and the output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "PromptList": { "type": "array", "items": { "$ref": "#/components/schemas/Prompt" } }, "PromptListEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/PromptList" }, { "type": "null" } ], "description": "Prompts of the brand (keyset-paginated catalog). null only when meta.schema_conformant is false and the output could not be mapped." }, "page": { "$ref": "#/components/schemas/KeysetPage" }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "page", "meta" ] }, "Prompt": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "country": { "type": "string" }, "is_active": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "topic_id": { "type": [ "string", "null" ] }, "topic_name": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_branded": { "type": "boolean" } }, "required": [ "id", "text", "country", "is_active", "archived_at", "topic_id", "topic_name", "tags", "created_at", "updated_at", "is_branded" ], "additionalProperties": {} }, "PromptEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/Prompt" }, { "type": "null" } ], "description": "One prompt of the brand. null only when meta.schema_conformant is false and the output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "RunOverviewReportRequest": { "type": "object", "properties": { "time_range": { "description": "Rolling window, or \"custom\" with start_date + end_date.", "default": "30d", "type": "string", "enum": [ "7d", "30d", "90d", "180d", "custom" ] }, "start_date": { "description": "Start of a custom window (UTC+8 business day, YYYY-MM-DD).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "description": "End of a custom window (UTC+8 business day, YYYY-MM-DD).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "platform": { "description": "AI platform, or \"all\".", "default": "all", "type": "string", "enum": [ "all", "chatgpt", "perplexity", "gemini", "google_ai", "copilot", "google_ai_overview" ] }, "topic_ids": { "description": "Restrict to these topic ids (1–50). \"_none\" = prompts without a topic.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "country": { "description": "ISO-2 country code of the prompts (e.g. US). Must be a country the brand has prompts in.", "type": "string", "minLength": 1, "maxLength": 8 } }, "additionalProperties": false }, "OverviewReport": { "oneOf": [ { "type": "object", "properties": { "kpi_state": { "type": "string", "const": "ok" }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "90d", "180d", "custom" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\", \"180d\", \"custom\"; more may be added." }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "end_bounded": { "type": "boolean" } }, "required": [ "time_range", "start_at", "end_at", "end_bounded" ], "additionalProperties": {} }, "platform": { "type": "string" }, "scope": { "type": "object", "properties": { "active": { "type": "boolean" }, "topic_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "collapsed": { "type": "boolean" } }, "required": [ "active", "topic_ids", "country", "collapsed" ], "additionalProperties": {} }, "kpi_caliber": { "type": "object", "properties": { "mention_rate": { "type": "string", "examples": [ "board", "fallback" ], "description": "[Extensible enum] Known values: \"board\", \"fallback\"; more may be added." }, "share_of_voice": { "type": "string", "examples": [ "board", "fallback" ], "description": "[Extensible enum] Known values: \"board\", \"fallback\"; more may be added." } }, "required": [ "mention_rate", "share_of_voice" ], "additionalProperties": {} }, "kpi_caliber_pending": { "type": "boolean" }, "has_prompts": { "type": "boolean" }, "has_completed_records": { "type": "boolean" }, "total_mentions": { "type": "integer", "minimum": 0 }, "ranked_records": { "type": "integer", "minimum": 0 }, "completed_records": { "type": "integer", "minimum": 0 }, "share_of_voice": { "type": [ "object", "null" ], "properties": { "share_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "brand_mentioned_records": { "type": "integer", "minimum": 0 }, "total_mentioned_records": { "type": "integer", "minimum": 0 } }, "required": [ "share_pct", "brand_mentioned_records", "total_mentioned_records" ], "additionalProperties": {} }, "share_of_voice_state": { "type": "string", "examples": [ "ok", "not_ready" ], "description": "[Extensible enum] Known values: \"ok\", \"not_ready\"; more may be added." }, "best_platform": { "type": [ "object", "null" ], "properties": { "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "visibility_score": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "platform_code", "platform_name", "visibility_score" ], "additionalProperties": {} }, "worst_platform": { "type": [ "object", "null" ], "properties": { "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "visibility_score": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "platform_code", "platform_name", "visibility_score" ], "additionalProperties": {} }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "visibility_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "citation_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "completed_records": { "type": "integer", "minimum": 0 }, "mentioned_records": { "type": "integer", "minimum": 0 }, "avg_position": { "type": [ "number", "null" ] }, "total_mentions": { "type": "integer", "minimum": 0 } }, "required": [ "platform_code", "platform_name", "visibility_score", "mention_rate_pct", "citation_rate_pct", "completed_records", "mentioned_records", "avg_position", "total_mentions" ], "additionalProperties": {} } }, "visibility_score": { "type": "number", "minimum": 0, "maximum": 100 }, "mention_rate_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "citation_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "avg_position": { "type": [ "number", "null" ] }, "top3_rate_pct": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "kpi_state", "window", "platform", "scope", "kpi_caliber", "kpi_caliber_pending", "has_prompts", "has_completed_records", "total_mentions", "ranked_records", "completed_records", "share_of_voice", "share_of_voice_state", "best_platform", "worst_platform", "platforms", "visibility_score", "mention_rate_pct", "citation_rate_pct", "avg_position", "top3_rate_pct" ], "additionalProperties": {} }, { "type": "object", "properties": { "kpi_state": { "type": "string", "const": "no_data" }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "90d", "180d", "custom" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\", \"180d\", \"custom\"; more may be added." }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "end_bounded": { "type": "boolean" } }, "required": [ "time_range", "start_at", "end_at", "end_bounded" ], "additionalProperties": {} }, "platform": { "type": "string" }, "scope": { "type": "object", "properties": { "active": { "type": "boolean" }, "topic_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "collapsed": { "type": "boolean" } }, "required": [ "active", "topic_ids", "country", "collapsed" ], "additionalProperties": {} }, "kpi_caliber": { "type": "object", "properties": { "mention_rate": { "type": "string", "examples": [ "board", "fallback" ], "description": "[Extensible enum] Known values: \"board\", \"fallback\"; more may be added." }, "share_of_voice": { "type": "string", "examples": [ "board", "fallback" ], "description": "[Extensible enum] Known values: \"board\", \"fallback\"; more may be added." } }, "required": [ "mention_rate", "share_of_voice" ], "additionalProperties": {} }, "kpi_caliber_pending": { "type": "boolean" }, "has_prompts": { "type": "boolean" }, "has_completed_records": { "type": "boolean" }, "total_mentions": { "type": "integer", "minimum": 0 }, "ranked_records": { "type": "integer", "minimum": 0 }, "completed_records": { "type": "integer", "minimum": 0 }, "share_of_voice": { "type": [ "object", "null" ], "properties": { "share_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "brand_mentioned_records": { "type": "integer", "minimum": 0 }, "total_mentioned_records": { "type": "integer", "minimum": 0 } }, "required": [ "share_pct", "brand_mentioned_records", "total_mentioned_records" ], "additionalProperties": {} }, "share_of_voice_state": { "type": "string", "examples": [ "ok", "not_ready" ], "description": "[Extensible enum] Known values: \"ok\", \"not_ready\"; more may be added." }, "best_platform": { "type": [ "object", "null" ], "properties": { "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "visibility_score": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "platform_code", "platform_name", "visibility_score" ], "additionalProperties": {} }, "worst_platform": { "type": [ "object", "null" ], "properties": { "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "visibility_score": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "platform_code", "platform_name", "visibility_score" ], "additionalProperties": {} }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "visibility_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "citation_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "completed_records": { "type": "integer", "minimum": 0 }, "mentioned_records": { "type": "integer", "minimum": 0 }, "avg_position": { "type": [ "number", "null" ] }, "total_mentions": { "type": "integer", "minimum": 0 } }, "required": [ "platform_code", "platform_name", "visibility_score", "mention_rate_pct", "citation_rate_pct", "completed_records", "mentioned_records", "avg_position", "total_mentions" ], "additionalProperties": {} } }, "visibility_score": { "type": "null" }, "mention_rate_pct": { "type": "null" }, "citation_rate_pct": { "type": "null" }, "avg_position": { "type": "null" }, "top3_rate_pct": { "type": "null" } }, "required": [ "kpi_state", "window", "platform", "scope", "kpi_caliber", "kpi_caliber_pending", "has_prompts", "has_completed_records", "total_mentions", "ranked_records", "completed_records", "share_of_voice", "share_of_voice_state", "best_platform", "worst_platform", "platforms", "visibility_score", "mention_rate_pct", "citation_rate_pct", "avg_position", "top3_rate_pct" ], "additionalProperties": {} }, { "type": "object", "properties": { "kpi_state": { "type": "string", "const": "unavailable" }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "90d", "180d", "custom" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\", \"180d\", \"custom\"; more may be added." }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "end_bounded": { "type": "boolean" } }, "required": [ "time_range", "start_at", "end_at", "end_bounded" ], "additionalProperties": {} }, "platform": { "type": "string" }, "scope": { "type": "object", "properties": { "active": { "type": "boolean" }, "topic_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "collapsed": { "type": "boolean" } }, "required": [ "active", "topic_ids", "country", "collapsed" ], "additionalProperties": {} }, "kpi_caliber": { "type": "null" }, "kpi_caliber_pending": { "type": "boolean", "const": false }, "has_prompts": { "type": "null" }, "has_completed_records": { "type": "null" }, "total_mentions": { "type": "null" }, "ranked_records": { "type": "null" }, "completed_records": { "type": "null" }, "share_of_voice": { "type": "null" }, "share_of_voice_state": { "type": "null" }, "best_platform": { "type": "null" }, "worst_platform": { "type": "null" }, "platforms": { "type": "null" }, "visibility_score": { "type": "null" }, "mention_rate_pct": { "type": "null" }, "citation_rate_pct": { "type": "null" }, "avg_position": { "type": "null" }, "top3_rate_pct": { "type": "null" } }, "required": [ "kpi_state", "window", "platform", "scope", "kpi_caliber", "kpi_caliber_pending", "has_prompts", "has_completed_records", "total_mentions", "ranked_records", "completed_records", "share_of_voice", "share_of_voice_state", "best_platform", "worst_platform", "platforms", "visibility_score", "mention_rate_pct", "citation_rate_pct", "avg_position", "top3_rate_pct" ], "additionalProperties": {} }, { "type": "object", "properties": { "kpi_state": { "type": "string", "const": "computing" }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "90d", "180d", "custom" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\", \"180d\", \"custom\"; more may be added." }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "end_bounded": { "type": "boolean" } }, "required": [ "time_range", "start_at", "end_at", "end_bounded" ], "additionalProperties": {} }, "platform": { "type": "string" }, "scope": { "type": "object", "properties": { "active": { "type": "boolean" }, "topic_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "collapsed": { "type": "boolean" } }, "required": [ "active", "topic_ids", "country", "collapsed" ], "additionalProperties": {} }, "kpi_caliber": { "type": "null" }, "kpi_caliber_pending": { "type": "boolean", "const": false }, "has_prompts": { "type": "boolean" }, "has_completed_records": { "type": "null" }, "total_mentions": { "type": "null" }, "ranked_records": { "type": "null" }, "completed_records": { "type": "null" }, "share_of_voice": { "type": "null" }, "share_of_voice_state": { "type": "null" }, "best_platform": { "type": "null" }, "worst_platform": { "type": "null" }, "platforms": { "type": "null" }, "visibility_score": { "type": "null" }, "mention_rate_pct": { "type": "null" }, "citation_rate_pct": { "type": "null" }, "avg_position": { "type": "null" }, "top3_rate_pct": { "type": "null" } }, "required": [ "kpi_state", "window", "platform", "scope", "kpi_caliber", "kpi_caliber_pending", "has_prompts", "has_completed_records", "total_mentions", "ranked_records", "completed_records", "share_of_voice", "share_of_voice_state", "best_platform", "worst_platform", "platforms", "visibility_score", "mention_rate_pct", "citation_rate_pct", "avg_position", "top3_rate_pct" ], "additionalProperties": {} } ] }, "OverviewReportEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/OverviewReport" }, { "type": "null" } ], "description": "The overview report. null only when meta.schema_conformant is false and the report output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "RunAnalyticsReportRequest": { "type": "object", "properties": { "start_utc_date": { "description": "First UTC record-day key (YYYY-MM-DD; = business day − 1). Passed to the report as start_date.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_utc_date": { "description": "Last UTC record-day key, inclusive (YYYY-MM-DD). Passed to the report as end_date. At most 366 days.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "breakdown": { "description": "One row per day × platform / per day / per day × topic.", "default": "platform", "type": "string", "enum": [ "platform", "total", "topic" ] }, "platform": { "description": "AI platform, or \"all\".", "default": "all", "type": "string", "enum": [ "all", "chatgpt", "gemini", "perplexity", "google_ai", "google_ai_overview" ] }, "topic_ids": { "description": "Restrict to these topic ids (1–50). \"_none\" = prompts without a topic.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "country": { "description": "ISO-2 country code of the prompts (e.g. US). Must be a country the brand has prompts in.", "type": "string", "minLength": 1, "maxLength": 8 }, "compare_previous": { "description": "Also return the previous equal-length window (previous / delta on every row and total).", "default": false, "type": "boolean" } }, "required": [ "start_utc_date", "end_utc_date" ], "additionalProperties": false }, "AnalyticsReport": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "ready" }, "reason": { "type": "null" }, "sentiment_not_ready_reason": { "type": [ "string", "null" ] }, "breakdown": { "type": "string", "examples": [ "platform", "total", "topic" ], "description": "[Extensible enum] Known values: \"platform\", \"total\", \"topic\"; more may be added." }, "window": { "type": "object", "properties": { "start_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "days": { "type": "integer", "minimum": 0 }, "days_with_data": { "type": [ "integer", "null" ], "minimum": 0 }, "current": { "type": [ "object", "null" ], "properties": { "start_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "days": { "type": "integer", "minimum": 0 }, "days_with_data": { "type": "integer", "minimum": 0 } }, "required": [ "start_utc_date", "end_utc_date", "days", "days_with_data" ], "additionalProperties": {} }, "previous": { "type": [ "object", "null" ], "properties": { "start_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "days": { "type": "integer", "minimum": 0 }, "days_with_data": { "type": "integer", "minimum": 0 } }, "required": [ "start_utc_date", "end_utc_date", "days", "days_with_data" ], "additionalProperties": {} } }, "required": [ "start_utc_date", "end_utc_date", "days", "days_with_data", "current", "previous" ], "additionalProperties": {} }, "platform": { "type": "string" }, "scope": { "type": "object", "properties": { "active": { "type": "boolean" }, "topic_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "collapsed": { "type": "boolean" } }, "required": [ "active", "topic_ids", "country", "collapsed" ], "additionalProperties": {} }, "rows": { "type": "array", "items": { "type": "object", "properties": { "utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "business_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "platform_code": { "type": [ "string", "null" ] }, "platform_name": { "type": [ "string", "null" ] }, "topic_id": { "type": [ "string", "null" ] }, "topic_name": { "type": [ "string", "null" ] }, "completed_records": { "type": "integer", "minimum": 0 }, "mentioned_records": { "type": "integer", "minimum": 0 }, "mention_count": { "type": "integer", "minimum": 0 }, "domain_cited_records": { "type": "integer", "minimum": 0 }, "visibility_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "domain_citation_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "sentiment": { "type": [ "object", "null" ], "properties": { "positive": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer", "minimum": 0 }, "negative": { "type": "integer", "minimum": 0 }, "mixed": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "scored_records": { "type": "integer", "minimum": 0 }, "avg_polarity": { "type": [ "number", "null" ], "minimum": -1, "maximum": 1 } }, "required": [ "positive", "neutral", "negative", "mixed", "unknown", "scored_records", "avg_polarity" ], "additionalProperties": {} }, "previous": { "type": [ "object", "null" ], "properties": { "utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "business_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "completed_records": { "type": "integer", "minimum": 0 }, "mentioned_records": { "type": "integer", "minimum": 0 }, "mention_count": { "type": "integer", "minimum": 0 }, "domain_cited_records": { "type": "integer", "minimum": 0 }, "visibility_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "domain_citation_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "sentiment": { "type": [ "object", "null" ], "properties": { "positive": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer", "minimum": 0 }, "negative": { "type": "integer", "minimum": 0 }, "mixed": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "scored_records": { "type": "integer", "minimum": 0 }, "avg_polarity": { "type": [ "number", "null" ], "minimum": -1, "maximum": 1 } }, "required": [ "positive", "neutral", "negative", "mixed", "unknown", "scored_records", "avg_polarity" ], "additionalProperties": {} } }, "required": [ "utc_date", "business_date", "completed_records", "mentioned_records", "mention_count", "domain_cited_records", "visibility_score", "mention_rate_pct", "domain_citation_rate_pct", "sentiment" ], "additionalProperties": {} }, "delta": { "type": [ "object", "null" ], "properties": { "completed_records": { "type": [ "number", "null" ] }, "mentioned_records": { "type": [ "number", "null" ] }, "mention_count": { "type": [ "number", "null" ] }, "domain_cited_records": { "type": [ "number", "null" ] }, "visibility_score": { "type": [ "number", "null" ] }, "mention_rate_pp": { "type": [ "number", "null" ] }, "domain_citation_rate_pp": { "type": [ "number", "null" ] }, "sentiment": { "type": [ "object", "null" ], "properties": { "positive": { "type": [ "number", "null" ] }, "neutral": { "type": [ "number", "null" ] }, "negative": { "type": [ "number", "null" ] }, "mixed": { "type": [ "number", "null" ] }, "unknown": { "type": [ "number", "null" ] }, "scored_records": { "type": [ "number", "null" ] }, "avg_polarity": { "type": [ "number", "null" ] } }, "required": [ "positive", "neutral", "negative", "mixed", "unknown", "scored_records", "avg_polarity" ], "additionalProperties": {} } }, "required": [ "completed_records", "mentioned_records", "mention_count", "domain_cited_records", "visibility_score", "mention_rate_pp", "domain_citation_rate_pp", "sentiment" ], "additionalProperties": {} } }, "required": [ "utc_date", "business_date", "platform_code", "platform_name", "topic_id", "topic_name", "completed_records", "mentioned_records", "mention_count", "domain_cited_records", "visibility_score", "mention_rate_pct", "domain_citation_rate_pct", "sentiment", "previous", "delta" ], "additionalProperties": {} } }, "totals": { "type": "array", "items": { "type": "object", "properties": { "utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "business_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "platform_code": { "type": [ "string", "null" ] }, "platform_name": { "type": [ "string", "null" ] }, "topic_id": { "type": [ "string", "null" ] }, "topic_name": { "type": [ "string", "null" ] }, "completed_records": { "type": "integer", "minimum": 0 }, "mentioned_records": { "type": "integer", "minimum": 0 }, "mention_count": { "type": "integer", "minimum": 0 }, "domain_cited_records": { "type": "integer", "minimum": 0 }, "visibility_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "domain_citation_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "sentiment": { "type": [ "object", "null" ], "properties": { "positive": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer", "minimum": 0 }, "negative": { "type": "integer", "minimum": 0 }, "mixed": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "scored_records": { "type": "integer", "minimum": 0 }, "avg_polarity": { "type": [ "number", "null" ], "minimum": -1, "maximum": 1 } }, "required": [ "positive", "neutral", "negative", "mixed", "unknown", "scored_records", "avg_polarity" ], "additionalProperties": {} }, "previous": { "type": [ "object", "null" ], "properties": { "utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "business_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "completed_records": { "type": "integer", "minimum": 0 }, "mentioned_records": { "type": "integer", "minimum": 0 }, "mention_count": { "type": "integer", "minimum": 0 }, "domain_cited_records": { "type": "integer", "minimum": 0 }, "visibility_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "domain_citation_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "sentiment": { "type": [ "object", "null" ], "properties": { "positive": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer", "minimum": 0 }, "negative": { "type": "integer", "minimum": 0 }, "mixed": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "scored_records": { "type": "integer", "minimum": 0 }, "avg_polarity": { "type": [ "number", "null" ], "minimum": -1, "maximum": 1 } }, "required": [ "positive", "neutral", "negative", "mixed", "unknown", "scored_records", "avg_polarity" ], "additionalProperties": {} } }, "required": [ "utc_date", "business_date", "completed_records", "mentioned_records", "mention_count", "domain_cited_records", "visibility_score", "mention_rate_pct", "domain_citation_rate_pct", "sentiment" ], "additionalProperties": {} }, "delta": { "type": [ "object", "null" ], "properties": { "completed_records": { "type": [ "number", "null" ] }, "mentioned_records": { "type": [ "number", "null" ] }, "mention_count": { "type": [ "number", "null" ] }, "domain_cited_records": { "type": [ "number", "null" ] }, "visibility_score": { "type": [ "number", "null" ] }, "mention_rate_pp": { "type": [ "number", "null" ] }, "domain_citation_rate_pp": { "type": [ "number", "null" ] }, "sentiment": { "type": [ "object", "null" ], "properties": { "positive": { "type": [ "number", "null" ] }, "neutral": { "type": [ "number", "null" ] }, "negative": { "type": [ "number", "null" ] }, "mixed": { "type": [ "number", "null" ] }, "unknown": { "type": [ "number", "null" ] }, "scored_records": { "type": [ "number", "null" ] }, "avg_polarity": { "type": [ "number", "null" ] } }, "required": [ "positive", "neutral", "negative", "mixed", "unknown", "scored_records", "avg_polarity" ], "additionalProperties": {} } }, "required": [ "completed_records", "mentioned_records", "mention_count", "domain_cited_records", "visibility_score", "mention_rate_pp", "domain_citation_rate_pp", "sentiment" ], "additionalProperties": {} } }, "required": [ "utc_date", "business_date", "platform_code", "platform_name", "topic_id", "topic_name", "completed_records", "mentioned_records", "mention_count", "domain_cited_records", "visibility_score", "mention_rate_pct", "domain_citation_rate_pct", "sentiment", "previous", "delta" ], "additionalProperties": {} } }, "capped": { "type": [ "object", "null" ], "properties": { "total_rows": { "type": "integer", "minimum": 0 }, "shown_rows": { "type": "integer", "minimum": 0 }, "shown_from_utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "total_groups": { "type": [ "integer", "null" ], "minimum": 0 }, "shown_groups": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "total_rows", "shown_rows", "shown_from_utc_date", "total_groups", "shown_groups" ], "additionalProperties": {} } }, "required": [ "status", "reason", "sentiment_not_ready_reason", "breakdown", "window", "platform", "scope", "rows", "totals", "capped" ], "additionalProperties": {} }, { "type": "object", "properties": { "status": { "type": "string", "const": "not_ready" }, "reason": { "type": "string" }, "breakdown": { "type": "string", "examples": [ "platform", "total", "topic" ], "description": "[Extensible enum] Known values: \"platform\", \"total\", \"topic\"; more may be added." }, "window": { "type": "object", "properties": { "start_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "days": { "type": "integer", "minimum": 0 }, "days_with_data": { "type": [ "integer", "null" ], "minimum": 0 }, "current": { "type": [ "object", "null" ], "properties": { "start_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "days": { "type": "integer", "minimum": 0 }, "days_with_data": { "type": "integer", "minimum": 0 } }, "required": [ "start_utc_date", "end_utc_date", "days", "days_with_data" ], "additionalProperties": {} }, "previous": { "type": [ "object", "null" ], "properties": { "start_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_utc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "days": { "type": "integer", "minimum": 0 }, "days_with_data": { "type": "integer", "minimum": 0 } }, "required": [ "start_utc_date", "end_utc_date", "days", "days_with_data" ], "additionalProperties": {} } }, "required": [ "start_utc_date", "end_utc_date", "days", "days_with_data", "current", "previous" ], "additionalProperties": {} }, "platform": { "type": "string" }, "scope": { "type": "object", "properties": { "active": { "type": "boolean" }, "topic_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "collapsed": { "type": "boolean" } }, "required": [ "active", "topic_ids", "country", "collapsed" ], "additionalProperties": {} }, "rows": { "maxItems": 0, "type": "array", "items": { "type": "object", "properties": { "utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "business_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "platform_code": { "type": [ "string", "null" ] }, "platform_name": { "type": [ "string", "null" ] }, "topic_id": { "type": [ "string", "null" ] }, "topic_name": { "type": [ "string", "null" ] }, "completed_records": { "type": "integer", "minimum": 0 }, "mentioned_records": { "type": "integer", "minimum": 0 }, "mention_count": { "type": "integer", "minimum": 0 }, "domain_cited_records": { "type": "integer", "minimum": 0 }, "visibility_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "domain_citation_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "sentiment": { "type": [ "object", "null" ], "properties": { "positive": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer", "minimum": 0 }, "negative": { "type": "integer", "minimum": 0 }, "mixed": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "scored_records": { "type": "integer", "minimum": 0 }, "avg_polarity": { "type": [ "number", "null" ], "minimum": -1, "maximum": 1 } }, "required": [ "positive", "neutral", "negative", "mixed", "unknown", "scored_records", "avg_polarity" ], "additionalProperties": {} }, "previous": { "type": [ "object", "null" ], "properties": { "utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "business_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "completed_records": { "type": "integer", "minimum": 0 }, "mentioned_records": { "type": "integer", "minimum": 0 }, "mention_count": { "type": "integer", "minimum": 0 }, "domain_cited_records": { "type": "integer", "minimum": 0 }, "visibility_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "domain_citation_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "sentiment": { "type": [ "object", "null" ], "properties": { "positive": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer", "minimum": 0 }, "negative": { "type": "integer", "minimum": 0 }, "mixed": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "scored_records": { "type": "integer", "minimum": 0 }, "avg_polarity": { "type": [ "number", "null" ], "minimum": -1, "maximum": 1 } }, "required": [ "positive", "neutral", "negative", "mixed", "unknown", "scored_records", "avg_polarity" ], "additionalProperties": {} } }, "required": [ "utc_date", "business_date", "completed_records", "mentioned_records", "mention_count", "domain_cited_records", "visibility_score", "mention_rate_pct", "domain_citation_rate_pct", "sentiment" ], "additionalProperties": {} }, "delta": { "type": [ "object", "null" ], "properties": { "completed_records": { "type": [ "number", "null" ] }, "mentioned_records": { "type": [ "number", "null" ] }, "mention_count": { "type": [ "number", "null" ] }, "domain_cited_records": { "type": [ "number", "null" ] }, "visibility_score": { "type": [ "number", "null" ] }, "mention_rate_pp": { "type": [ "number", "null" ] }, "domain_citation_rate_pp": { "type": [ "number", "null" ] }, "sentiment": { "type": [ "object", "null" ], "properties": { "positive": { "type": [ "number", "null" ] }, "neutral": { "type": [ "number", "null" ] }, "negative": { "type": [ "number", "null" ] }, "mixed": { "type": [ "number", "null" ] }, "unknown": { "type": [ "number", "null" ] }, "scored_records": { "type": [ "number", "null" ] }, "avg_polarity": { "type": [ "number", "null" ] } }, "required": [ "positive", "neutral", "negative", "mixed", "unknown", "scored_records", "avg_polarity" ], "additionalProperties": {} } }, "required": [ "completed_records", "mentioned_records", "mention_count", "domain_cited_records", "visibility_score", "mention_rate_pp", "domain_citation_rate_pp", "sentiment" ], "additionalProperties": {} } }, "required": [ "utc_date", "business_date", "platform_code", "platform_name", "topic_id", "topic_name", "completed_records", "mentioned_records", "mention_count", "domain_cited_records", "visibility_score", "mention_rate_pct", "domain_citation_rate_pct", "sentiment", "previous", "delta" ], "additionalProperties": {} } }, "totals": { "type": "null" }, "capped": { "type": "null" } }, "required": [ "status", "reason", "breakdown", "window", "platform", "scope", "rows", "totals", "capped" ], "additionalProperties": {} } ] }, "AnalyticsReportEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/AnalyticsReport" }, { "type": "null" } ], "description": "The analytics report. null only when meta.schema_conformant is false and the report output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "RunBrandBoardReportRequest": { "type": "object", "properties": { "time_range": { "description": "Rolling window, or \"custom\" with start_date + end_date. 180d is billed at twice the base price.", "default": "30d", "type": "string", "enum": [ "7d", "30d", "90d", "180d", "custom" ] }, "start_date": { "description": "Start of a custom window (UTC+8 business day, YYYY-MM-DD).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "description": "End of a custom window (UTC+8 business day, YYYY-MM-DD).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "platform": { "description": "AI platform; omit for all platforms. Combines freely with topic_ids / country.", "type": "string", "enum": [ "chatgpt", "perplexity", "gemini", "google_ai", "copilot", "google_ai_overview" ] }, "topic_ids": { "description": "Restrict to these topic ids (1–50). \"_none\" = prompts without a topic.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "country": { "description": "ISO-2 country code of the prompts (e.g. US). Must be a country the brand has prompts in.", "type": "string", "minLength": 1, "maxLength": 8 }, "limit": { "description": "Top-N rows (1–50).", "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "include_trend": { "description": "Also return the daily mention-rate trend (confirmed mode only).", "default": false, "type": "boolean" } }, "additionalProperties": false }, "BrandBoardReport": { "oneOf": [ { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "confirmed" }, "status": { "type": "string", "const": "ok" }, "caliber": { "type": "string", "examples": [ "tracked_brand_v1", "brand_entity_v1", "scoped_open_world_v0" ], "description": "[Extensible enum] Known values: \"tracked_brand_v1\", \"brand_entity_v1\", \"scoped_open_world_v0\"; more may be added." }, "reason": { "type": [ "string", "null" ] }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "90d", "180d", "custom" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\", \"180d\", \"custom\"; more may be added." }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "end_bounded": { "type": "boolean" } }, "required": [ "time_range", "start_at", "end_at", "end_bounded" ], "additionalProperties": {} }, "platform": { "type": "string" }, "scope": { "type": "object", "properties": { "active": { "type": "boolean" }, "topic_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "collapsed": { "type": "boolean" } }, "required": [ "active", "topic_ids", "country", "collapsed" ], "additionalProperties": {} }, "completed_records": { "type": "integer", "minimum": 0 }, "completed_source": { "type": "string", "examples": [ "tracked", "derived", "live" ], "description": "[Extensible enum] Known values: \"tracked\", \"derived\", \"live\"; more may be added." }, "own_brand": { "type": "object", "properties": { "name": { "type": "string" }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "share_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mentioned_records": { "type": [ "integer", "null" ], "minimum": 0 }, "rank": { "type": [ "integer", "null" ], "minimum": 0 }, "pending": { "type": "boolean" }, "computing": { "type": "boolean" } }, "required": [ "name", "mention_rate_pct", "share_pct", "mentioned_records", "rank", "pending", "computing" ], "additionalProperties": {} }, "mention_rate_leaders": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 0 }, "entity_id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "examples": [ "manual", "auto" ], "description": "[Extensible enum] Known values: \"manual\", \"auto\"; more may be added." }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "share_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mentioned_records": { "type": [ "integer", "null" ], "minimum": 0 }, "computing": { "type": "boolean" } }, "required": [ "rank", "entity_id", "name", "source", "mention_rate_pct", "share_pct", "mentioned_records", "computing" ], "additionalProperties": {} } }, "total": { "type": "integer", "minimum": 0 }, "returned": { "type": "integer", "minimum": 0 }, "coverage": { "type": [ "object", "null" ], "properties": { "floor_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "window_start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "clamped": { "type": "boolean" } }, "required": [ "floor_date", "window_start_date", "clamped" ], "additionalProperties": {} }, "unmapped": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": {} } }, "trend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "business_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "brand_mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "completed_records": { "type": "integer", "minimum": 0 }, "brand_mentioned_records": { "type": [ "integer", "null" ], "minimum": 0 }, "competitors": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "string" }, "name": { "type": "string" }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mentioned_records": { "type": "integer", "minimum": 0 } }, "required": [ "entity_id", "name", "mention_rate_pct", "mentioned_records" ], "additionalProperties": {} } } }, "required": [ "business_date", "brand_mention_rate_pct", "completed_records", "brand_mentioned_records", "competitors" ], "additionalProperties": {} } }, "trend_competitors": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "entity_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "entity_id", "name" ], "additionalProperties": {} } }, "trend_meta": { "type": [ "object", "null" ], "properties": { "days": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean" }, "first_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "latest_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "days", "truncated", "first_date", "latest_date" ], "additionalProperties": {} } }, "required": [ "mode", "status", "caliber", "reason", "brand", "window", "platform", "scope", "completed_records", "completed_source", "own_brand", "mention_rate_leaders", "rows", "total", "returned", "coverage", "unmapped", "trend", "trend_competitors", "trend_meta" ], "additionalProperties": {} }, { "type": "object", "properties": { "mode": { "type": "string", "const": "confirmed" }, "status": { "type": "string", "const": "not_ready" }, "caliber": { "type": "string", "examples": [ "tracked_brand_v1", "brand_entity_v1", "scoped_open_world_v0" ], "description": "[Extensible enum] Known values: \"tracked_brand_v1\", \"brand_entity_v1\", \"scoped_open_world_v0\"; more may be added." }, "reason": { "type": [ "string", "null" ] }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "90d", "180d", "custom" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\", \"180d\", \"custom\"; more may be added." }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "end_bounded": { "type": "boolean" } }, "required": [ "time_range", "start_at", "end_at", "end_bounded" ], "additionalProperties": {} }, "platform": { "type": "string" }, "scope": { "type": "object", "properties": { "active": { "type": "boolean" }, "topic_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "collapsed": { "type": "boolean" } }, "required": [ "active", "topic_ids", "country", "collapsed" ], "additionalProperties": {} }, "completed_records": { "type": "null" }, "completed_source": { "type": "null" }, "own_brand": { "type": "null" }, "mention_rate_leaders": { "type": "null" }, "rows": { "maxItems": 0, "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 0 }, "entity_id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "examples": [ "manual", "auto" ], "description": "[Extensible enum] Known values: \"manual\", \"auto\"; more may be added." }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "share_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mentioned_records": { "type": [ "integer", "null" ], "minimum": 0 }, "computing": { "type": "boolean" } }, "required": [ "rank", "entity_id", "name", "source", "mention_rate_pct", "share_pct", "mentioned_records", "computing" ], "additionalProperties": {} } }, "total": { "type": "null" }, "returned": { "type": "null" }, "unmapped": { "type": "null" }, "trend": { "type": "null" }, "trend_competitors": { "type": "null" }, "trend_meta": { "type": "null" }, "coverage": { "type": "null" } }, "required": [ "mode", "status", "caliber", "reason", "brand", "window", "platform", "scope", "completed_records", "completed_source", "own_brand", "mention_rate_leaders", "rows", "total", "returned", "unmapped", "trend", "trend_competitors", "trend_meta", "coverage" ], "additionalProperties": {} }, { "type": "object", "properties": { "mode": { "type": "string", "const": "confirmed" }, "status": { "type": "string", "const": "no_coverage" }, "caliber": { "type": "string", "examples": [ "tracked_brand_v1", "brand_entity_v1", "scoped_open_world_v0" ], "description": "[Extensible enum] Known values: \"tracked_brand_v1\", \"brand_entity_v1\", \"scoped_open_world_v0\"; more may be added." }, "reason": { "type": [ "string", "null" ] }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "90d", "180d", "custom" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\", \"180d\", \"custom\"; more may be added." }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "end_bounded": { "type": "boolean" } }, "required": [ "time_range", "start_at", "end_at", "end_bounded" ], "additionalProperties": {} }, "platform": { "type": "string" }, "scope": { "type": "object", "properties": { "active": { "type": "boolean" }, "topic_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "collapsed": { "type": "boolean" } }, "required": [ "active", "topic_ids", "country", "collapsed" ], "additionalProperties": {} }, "completed_records": { "type": "null" }, "completed_source": { "type": "null" }, "own_brand": { "type": "null" }, "mention_rate_leaders": { "type": "null" }, "rows": { "maxItems": 0, "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 0 }, "entity_id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "examples": [ "manual", "auto" ], "description": "[Extensible enum] Known values: \"manual\", \"auto\"; more may be added." }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "share_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mentioned_records": { "type": [ "integer", "null" ], "minimum": 0 }, "computing": { "type": "boolean" } }, "required": [ "rank", "entity_id", "name", "source", "mention_rate_pct", "share_pct", "mentioned_records", "computing" ], "additionalProperties": {} } }, "total": { "type": "null" }, "returned": { "type": "null" }, "unmapped": { "type": "null" }, "trend": { "type": "null" }, "trend_competitors": { "type": "null" }, "trend_meta": { "type": "null" }, "coverage": { "type": "object", "properties": { "floor_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "window_start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "clamped": { "type": "boolean" } }, "required": [ "floor_date", "window_start_date", "clamped" ], "additionalProperties": {} } }, "required": [ "mode", "status", "caliber", "reason", "brand", "window", "platform", "scope", "completed_records", "completed_source", "own_brand", "mention_rate_leaders", "rows", "total", "returned", "unmapped", "trend", "trend_competitors", "trend_meta", "coverage" ], "additionalProperties": {} } ] }, { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "scoped_open_world" }, "status": { "type": "string", "const": "ok" }, "caliber": { "type": "string", "examples": [ "tracked_brand_v1", "brand_entity_v1", "scoped_open_world_v0" ], "description": "[Extensible enum] Known values: \"tracked_brand_v1\", \"brand_entity_v1\", \"scoped_open_world_v0\"; more may be added." }, "reason": { "type": [ "string", "null" ] }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "90d", "180d", "custom" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\", \"180d\", \"custom\"; more may be added." }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "end_bounded": { "type": "boolean" } }, "required": [ "time_range", "start_at", "end_at", "end_bounded" ], "additionalProperties": {} }, "platform": { "type": "string" }, "scope": { "type": "object", "properties": { "active": { "type": "boolean" }, "topic_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "collapsed": { "type": "boolean" } }, "required": [ "active", "topic_ids", "country", "collapsed" ], "additionalProperties": {} }, "completed_records": { "type": [ "integer", "null" ], "minimum": 0 }, "completed_source": { "type": [ "string", "null" ], "examples": [ "derived", "live" ], "description": "[Extensible enum] Known values: \"derived\", \"live\"; more may be added." }, "rows": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 0 }, "entity_id": { "type": "string" }, "name": { "type": "string" }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "candidate_share_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mentioned_records": { "type": "integer", "minimum": 0 }, "sum_mentions": { "type": "integer", "minimum": 0 }, "has_votes": { "type": "boolean" }, "auto_confirmed": { "type": "boolean" } }, "required": [ "rank", "entity_id", "name", "mention_rate_pct", "candidate_share_pct", "mentioned_records", "sum_mentions", "has_votes", "auto_confirmed" ], "additionalProperties": {} } }, "total": { "type": "integer", "minimum": 0 }, "returned": { "type": "integer", "minimum": 0 }, "candidate_cap": { "type": "integer", "minimum": 0 }, "candidate_truncated": { "type": "boolean" } }, "required": [ "mode", "status", "caliber", "reason", "brand", "window", "platform", "scope", "completed_records", "completed_source", "rows", "total", "returned", "candidate_cap", "candidate_truncated" ], "additionalProperties": {} }, { "type": "object", "properties": { "mode": { "type": "string", "const": "scoped_open_world" }, "status": { "type": "string", "const": "not_ready" }, "caliber": { "type": "string", "examples": [ "tracked_brand_v1", "brand_entity_v1", "scoped_open_world_v0" ], "description": "[Extensible enum] Known values: \"tracked_brand_v1\", \"brand_entity_v1\", \"scoped_open_world_v0\"; more may be added." }, "reason": { "type": [ "string", "null" ] }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "90d", "180d", "custom" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\", \"180d\", \"custom\"; more may be added." }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "end_bounded": { "type": "boolean" } }, "required": [ "time_range", "start_at", "end_at", "end_bounded" ], "additionalProperties": {} }, "platform": { "type": "string" }, "scope": { "type": "object", "properties": { "active": { "type": "boolean" }, "topic_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "collapsed": { "type": "boolean" } }, "required": [ "active", "topic_ids", "country", "collapsed" ], "additionalProperties": {} }, "completed_records": { "type": "null" }, "completed_source": { "type": "null" }, "rows": { "maxItems": 0, "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 0 }, "entity_id": { "type": "string" }, "name": { "type": "string" }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "candidate_share_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mentioned_records": { "type": "integer", "minimum": 0 }, "sum_mentions": { "type": "integer", "minimum": 0 }, "has_votes": { "type": "boolean" }, "auto_confirmed": { "type": "boolean" } }, "required": [ "rank", "entity_id", "name", "mention_rate_pct", "candidate_share_pct", "mentioned_records", "sum_mentions", "has_votes", "auto_confirmed" ], "additionalProperties": {} } }, "total": { "type": "null" }, "returned": { "type": "null" }, "candidate_cap": { "type": "null" }, "candidate_truncated": { "type": "null" } }, "required": [ "mode", "status", "caliber", "reason", "brand", "window", "platform", "scope", "completed_records", "completed_source", "rows", "total", "returned", "candidate_cap", "candidate_truncated" ], "additionalProperties": {} } ] } ] }, "BrandBoardReportEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/BrandBoardReport" }, { "type": "null" } ], "description": "The brand-board report. null only when meta.schema_conformant is false and the report output could not be mapped." }, "page": { "$ref": "#/components/schemas/TopNPage" }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "page", "meta" ] }, "RunCitationsReportRequest": { "type": "object", "properties": { "time_range": { "description": "Rolling window of closed business days.", "default": "30d", "type": "string", "enum": [ "7d", "30d", "90d" ] }, "platform": { "description": "AI platform, or \"all\".", "default": "all", "type": "string", "enum": [ "all", "chatgpt", "perplexity", "gemini", "google_ai", "copilot", "google_ai_overview" ] }, "topic_ids": { "description": "Restrict to these topic ids (1–50). With a filter, `stats` is null and `filtered` is true.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "additionalProperties": false }, "CitationsReport": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "ready" }, "reason": { "type": "null" }, "filtered": { "type": "boolean" }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "90d" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\"; more may be added." }, "days": { "type": "integer", "minimum": 0 }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "prev_start_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "prev_end_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "today_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "closed_empty": { "type": "boolean" } }, "required": [ "time_range", "days", "start_date", "end_date", "prev_start_date", "prev_end_date", "today_date", "closed_empty" ], "additionalProperties": {} }, "stats_caliber": { "type": [ "string", "null" ], "examples": [ "created_day", "legacy" ], "description": "[Extensible enum] Known values: \"created_day\", \"legacy\"; more may be added." }, "stats_window": { "type": [ "object", "null" ], "properties": { "axis": { "type": "string", "examples": [ "citation_created_day", "record_date" ], "description": "[Extensible enum] Known values: \"citation_created_day\", \"record_date\"; more may be added." }, "timezone": { "type": "string" }, "time_range": { "type": "string", "examples": [ "7d", "30d", "90d" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\"; more may be added." }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "closed_end_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "as_of_at": { "type": "string", "format": "date-time" } }, "required": [ "axis", "timezone", "time_range", "start_date", "end_date", "closed_end_date", "as_of_at" ], "additionalProperties": {} }, "stats": { "type": [ "object", "null" ], "properties": { "total_citations": { "type": "integer", "minimum": 0 }, "unique_root_domains": { "type": "integer", "minimum": 0 }, "daily": { "type": "array", "items": { "type": "object", "properties": { "business_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "citations": { "type": "integer", "minimum": 0 }, "brand_citations": { "type": "integer", "minimum": 0 } }, "required": [ "business_date", "utc_date", "citations", "brand_citations" ], "additionalProperties": {} } }, "ownership": { "type": "object", "properties": { "brand_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "competitor_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "third_party_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "brand_owned_citations": { "type": "integer", "minimum": 0 }, "competitor_owned_citations": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "brand_pct", "competitor_pct", "third_party_pct", "brand_owned_citations", "competitor_owned_citations" ], "additionalProperties": {} }, "brand_subdomains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 } }, "required": [ "domain", "citations" ], "additionalProperties": {} } }, "top_domains": { "type": "array", "items": { "type": "object", "properties": { "root_domain": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 }, "share_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "is_brand_domain": { "type": "boolean" }, "domain_type": { "type": [ "string", "null" ], "examples": [ "you", "competitor", "other" ], "description": "[Extensible enum] Known values: \"you\", \"competitor\", \"other\"; more may be added." } }, "required": [ "root_domain", "citations", "share_ratio", "is_brand_domain", "domain_type" ], "additionalProperties": {} } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 }, "share_ratio": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "platform_code", "platform_name", "citations", "share_ratio" ], "additionalProperties": {} } } }, "required": [ "total_citations", "unique_root_domains", "daily", "ownership", "brand_subdomains", "top_domains", "platforms" ], "additionalProperties": {} }, "prev_ready": { "type": [ "boolean", "null" ] }, "coverage": { "type": "object", "properties": { "ready_dates": { "type": "array", "items": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "missing_dates": { "type": "array", "items": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "as_of_at": { "type": "string", "format": "date-time" } }, "required": [ "ready_dates", "missing_dates", "as_of_at" ], "additionalProperties": {} }, "invalid_filter": { "type": [ "string", "null" ], "examples": [ "competitors" ], "description": "[Extensible enum] Known values: \"competitors\"; more may be added." }, "totals": { "type": "object", "properties": { "root_domains": { "type": "integer", "minimum": 0 }, "citations": { "type": "integer", "minimum": 0 } }, "required": [ "root_domains", "citations" ], "additionalProperties": {} }, "you": { "type": [ "object", "null" ], "properties": { "root_domains": { "type": "array", "items": { "type": "string" } }, "citations": { "type": "integer", "minimum": 0 }, "share_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "rank": { "type": "integer", "minimum": 0 } }, "required": [ "root_domains", "citations", "share_ratio", "rank" ], "additionalProperties": {} }, "movers": { "type": "object", "properties": { "top": { "type": "array", "items": { "type": "object", "properties": { "root_domain": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 }, "prev_citations": { "type": [ "integer", "null" ], "minimum": 0 }, "citations_change_pct": { "type": [ "number", "null" ] }, "is_new": { "type": "boolean" } }, "required": [ "root_domain", "citations", "prev_citations", "citations_change_pct", "is_new" ], "additionalProperties": {} } }, "new": { "type": "array", "items": { "type": "object", "properties": { "root_domain": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 }, "prev_citations": { "type": [ "integer", "null" ], "minimum": 0 }, "citations_change_pct": { "type": [ "number", "null" ] }, "is_new": { "type": "boolean" } }, "required": [ "root_domain", "citations", "prev_citations", "citations_change_pct", "is_new" ], "additionalProperties": {} } }, "up": { "type": "array", "items": { "type": "object", "properties": { "root_domain": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 }, "prev_citations": { "type": [ "integer", "null" ], "minimum": 0 }, "citations_change_pct": { "type": [ "number", "null" ] }, "is_new": { "type": "boolean" } }, "required": [ "root_domain", "citations", "prev_citations", "citations_change_pct", "is_new" ], "additionalProperties": {} } }, "down": { "type": "array", "items": { "type": "object", "properties": { "root_domain": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 }, "prev_citations": { "type": [ "integer", "null" ], "minimum": 0 }, "citations_change_pct": { "type": [ "number", "null" ] }, "is_new": { "type": "boolean" } }, "required": [ "root_domain", "citations", "prev_citations", "citations_change_pct", "is_new" ], "additionalProperties": {} } } }, "required": [ "top", "new", "up", "down" ], "additionalProperties": {} }, "entered_top20": { "type": "array", "items": { "type": "string" } }, "biggest_drop": { "type": [ "object", "null" ], "properties": { "root_domain": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 }, "prev_citations": { "type": [ "integer", "null" ], "minimum": 0 }, "citations_change_pct": { "type": [ "number", "null" ] }, "is_new": { "type": "boolean" } }, "required": [ "root_domain", "citations", "prev_citations", "citations_change_pct", "is_new" ], "additionalProperties": {} }, "trend": { "type": "object", "properties": { "default_granularity": { "type": "string", "examples": [ "day", "week", "month" ], "description": "[Extensible enum] Known values: \"day\", \"week\", \"month\"; more may be added." }, "business_dates": { "type": "array", "items": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "series": { "type": "array", "items": { "type": "object", "properties": { "root_domain": { "type": "string" }, "is_you": { "type": "boolean" }, "values": { "type": "array", "items": { "type": [ "integer", "null" ], "minimum": 0 } } }, "required": [ "root_domain", "is_you", "values" ], "additionalProperties": {} } }, "first_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "default_granularity", "business_dates", "series", "first_date" ], "additionalProperties": {} }, "citations_by_type": { "type": "object", "properties": { "you": { "type": "integer", "minimum": 0 }, "competitor": { "type": "integer", "minimum": 0 }, "other": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "you", "competitor", "other", "total" ], "additionalProperties": {} } }, "required": [ "status", "reason", "filtered", "window", "stats_caliber", "stats_window", "stats", "prev_ready", "coverage", "invalid_filter", "totals", "you", "movers", "entered_top20", "biggest_drop", "trend", "citations_by_type" ], "additionalProperties": {} }, { "type": "object", "properties": { "status": { "type": "string", "const": "not_ready" }, "reason": { "type": "string" }, "filtered": { "type": "boolean" }, "window": { "type": "object", "properties": { "time_range": { "type": "string", "examples": [ "7d", "30d", "90d" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\"; more may be added." }, "days": { "type": "integer", "minimum": 0 }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "prev_start_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "prev_end_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "today_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "closed_empty": { "type": "boolean" } }, "required": [ "time_range", "days", "start_date", "end_date", "prev_start_date", "prev_end_date", "today_date", "closed_empty" ], "additionalProperties": {} }, "stats_caliber": { "type": [ "string", "null" ], "examples": [ "created_day", "legacy" ], "description": "[Extensible enum] Known values: \"created_day\", \"legacy\"; more may be added." }, "stats_window": { "type": [ "object", "null" ], "properties": { "axis": { "type": "string", "examples": [ "citation_created_day", "record_date" ], "description": "[Extensible enum] Known values: \"citation_created_day\", \"record_date\"; more may be added." }, "timezone": { "type": "string" }, "time_range": { "type": "string", "examples": [ "7d", "30d", "90d" ], "description": "[Extensible enum] Known values: \"7d\", \"30d\", \"90d\"; more may be added." }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "closed_end_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "as_of_at": { "type": "string", "format": "date-time" } }, "required": [ "axis", "timezone", "time_range", "start_date", "end_date", "closed_end_date", "as_of_at" ], "additionalProperties": {} }, "stats": { "type": [ "object", "null" ], "properties": { "total_citations": { "type": "integer", "minimum": 0 }, "unique_root_domains": { "type": "integer", "minimum": 0 }, "daily": { "type": "array", "items": { "type": "object", "properties": { "business_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "utc_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "citations": { "type": "integer", "minimum": 0 }, "brand_citations": { "type": "integer", "minimum": 0 } }, "required": [ "business_date", "utc_date", "citations", "brand_citations" ], "additionalProperties": {} } }, "ownership": { "type": "object", "properties": { "brand_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "competitor_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "third_party_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "brand_owned_citations": { "type": "integer", "minimum": 0 }, "competitor_owned_citations": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "brand_pct", "competitor_pct", "third_party_pct", "brand_owned_citations", "competitor_owned_citations" ], "additionalProperties": {} }, "brand_subdomains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 } }, "required": [ "domain", "citations" ], "additionalProperties": {} } }, "top_domains": { "type": "array", "items": { "type": "object", "properties": { "root_domain": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 }, "share_ratio": { "type": "number", "minimum": 0, "maximum": 1 }, "is_brand_domain": { "type": "boolean" }, "domain_type": { "type": [ "string", "null" ], "examples": [ "you", "competitor", "other" ], "description": "[Extensible enum] Known values: \"you\", \"competitor\", \"other\"; more may be added." } }, "required": [ "root_domain", "citations", "share_ratio", "is_brand_domain", "domain_type" ], "additionalProperties": {} } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform_code": { "type": "string" }, "platform_name": { "type": "string" }, "citations": { "type": "integer", "minimum": 0 }, "share_ratio": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "platform_code", "platform_name", "citations", "share_ratio" ], "additionalProperties": {} } } }, "required": [ "total_citations", "unique_root_domains", "daily", "ownership", "brand_subdomains", "top_domains", "platforms" ], "additionalProperties": {} }, "prev_ready": { "type": "null" }, "coverage": { "type": "null" }, "invalid_filter": { "type": "null" }, "totals": { "type": "null" }, "you": { "type": "null" }, "movers": { "type": "null" }, "entered_top20": { "type": "null" }, "biggest_drop": { "type": "null" }, "trend": { "type": "null" }, "citations_by_type": { "type": "null" } }, "required": [ "status", "reason", "filtered", "window", "stats_caliber", "stats_window", "stats", "prev_ready", "coverage", "invalid_filter", "totals", "you", "movers", "entered_top20", "biggest_drop", "trend", "citations_by_type" ], "additionalProperties": {} } ] }, "CitationsReportEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/CitationsReport" }, { "type": "null" } ], "description": "The citations report. null only when meta.schema_conformant is false and the report output could not be mapped." }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "meta" ] }, "RunPromptsReportRequest": { "type": "object", "properties": { "limit": { "description": "Rows per page (1–100).", "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "description": "Opaque cursor from page.next_cursor. Must be sent with exactly the same filters and limit.", "type": "string", "minLength": 1, "maxLength": 512 }, "search": { "description": "Case-insensitive substring of the prompt text or a tag name.", "type": "string", "minLength": 1, "maxLength": 200 }, "sort_by": { "description": "Sort key. Omit for the default: created_at for status=active, archived_at for status=archived.", "type": "string", "enum": [ "text", "visibility", "mention_rate", "citations", "created_at", "archived_at" ] }, "sort_order": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "time_range": { "description": "Metrics window. Ignored when start_date + end_date are given.", "default": "30d", "type": "string", "enum": [ "7d", "30d", "90d" ] }, "start_date": { "description": "Start of an exact metrics window; send together with end_date (UTC+8 business day, YYYY-MM-DD).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "description": "End of an exact metrics window; send together with start_date (UTC+8 business day, YYYY-MM-DD).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "platform": { "description": "AI platform, or \"all\".", "default": "all", "type": "string", "enum": [ "all", "chatgpt", "perplexity", "gemini", "google_ai", "copilot", "google_ai_overview" ] }, "topic_ids": { "description": "Restrict to these topic ids (1–50). \"_none\" = prompts without a topic.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "tags": { "description": "Restrict to prompts carrying these tags. \"_none\" = untagged prompts.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "status": { "description": "Monitored prompts, or archived ones.", "default": "active", "type": "string", "enum": [ "active", "archived" ] }, "country": { "description": "ISO-2 country code of the prompts (e.g. US). Must be a country the brand has prompts in.", "type": "string", "minLength": 1, "maxLength": 8 }, "include_competitors": { "description": "Also compute share of voice and competitor mentions per prompt (slower on large brands).", "default": false, "type": "boolean" } }, "additionalProperties": false }, "PromptsReport": { "type": "object", "properties": { "prompts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "country": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "topic_id": { "type": [ "string", "null" ] }, "topic_name": { "type": [ "string", "null" ] }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "is_branded": { "type": [ "boolean", "null" ] }, "in_flight_records": { "type": [ "integer", "null" ], "minimum": 0 }, "records": { "type": "integer", "minimum": 0 }, "citations": { "type": "integer", "minimum": 0 }, "brand_citation_records": { "type": "integer", "minimum": 0 }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform_code": { "type": "string" }, "position": { "type": [ "number", "null" ] }, "mentions": { "type": [ "number", "null" ] }, "status": { "type": "string" }, "record_date_at": { "type": "string", "format": "date-time" } }, "required": [ "platform_code", "position", "mentions", "status", "record_date_at" ], "additionalProperties": {} } }, "performance": { "type": "object", "properties": { "total_mentions": { "type": "integer", "minimum": 0 }, "avg_position": { "type": [ "number", "null" ] }, "has_top3": { "type": "boolean" }, "has_top5": { "type": "boolean" }, "has_top10": { "type": "boolean" } }, "required": [ "total_mentions", "avg_position", "has_top3", "has_top5", "has_top10" ], "additionalProperties": {} }, "geo_metrics": { "type": [ "object", "null" ], "properties": { "visibility_score": { "type": "number", "minimum": 0, "maximum": 100 }, "mention_rate_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "citation_rate_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "mentioned_records": { "type": "integer", "minimum": 0 }, "completed_records": { "type": "integer", "minimum": 0 }, "delta": { "type": [ "object", "null" ], "properties": { "visibility_score": { "type": [ "number", "null" ] }, "avg_position": { "type": [ "number", "null" ] }, "citation_rate_pp": { "type": [ "number", "null" ] }, "share_pp": { "type": [ "number", "null" ] } }, "required": [ "visibility_score", "avg_position", "citation_rate_pp", "share_pp" ], "additionalProperties": {} }, "delta_insufficient": { "type": "object", "properties": { "visibility_score": { "type": "boolean" } }, "required": [ "visibility_score" ], "additionalProperties": {} } }, "required": [ "visibility_score", "mention_rate_pct", "citation_rate_pct", "mentioned_records", "completed_records", "delta", "delta_insufficient" ], "additionalProperties": {} }, "competitors_state": { "type": "string", "examples": [ "deferred", "included" ], "description": "[Extensible enum] Known values: \"deferred\", \"included\"; more may be added." }, "som": { "type": [ "object", "null" ], "properties": { "share_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "rank": { "type": [ "integer", "null" ], "minimum": 0 }, "total_competitors": { "type": "integer", "minimum": 0 } }, "required": [ "share_pct", "rank", "total_competitors" ], "additionalProperties": {} }, "competitor_mentions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "mentioned_records": { "type": "integer", "minimum": 0 }, "share_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "domain": { "type": [ "string", "null" ] } }, "required": [ "name", "mentioned_records", "share_pct", "domain" ], "additionalProperties": {} } } }, "required": [ "id", "text", "category", "tags", "country", "is_active", "topic_id", "topic_name", "archived_at", "created_at", "is_branded", "in_flight_records", "records", "citations", "brand_citation_records", "platforms", "performance", "geo_metrics", "competitors_state", "som", "competitor_mentions" ], "additionalProperties": {} } }, "summary": { "type": "object", "properties": { "visibility_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "mention_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "citation_rate_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "delta": { "type": "object", "properties": { "visibility_score": { "type": [ "number", "null" ] }, "mention_rate_pp": { "type": [ "number", "null" ] }, "citation_rate_pp": { "type": [ "number", "null" ] } }, "required": [ "visibility_score", "mention_rate_pp", "citation_rate_pp" ], "additionalProperties": {} }, "delta_insufficient": { "type": "object", "properties": { "visibility_score": { "type": "boolean" }, "mention_rate_pp": { "type": "boolean" }, "citation_rate_pp": { "type": "boolean" } }, "required": [ "visibility_score", "mention_rate_pp", "citation_rate_pp" ], "additionalProperties": {} } }, "required": [ "visibility_score", "mention_rate_pct", "citation_rate_pct", "delta", "delta_insufficient" ], "additionalProperties": {} }, "competitors_included": { "type": "boolean" }, "country_options": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "prompts", "summary", "competitors_included", "country_options" ], "additionalProperties": {} }, "PromptsReportEnvelope": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/PromptsReport" }, { "type": "null" } ], "description": "The prompts report. null only when meta.schema_conformant is false and the report output could not be mapped." }, "page": { "$ref": "#/components/schemas/CursorPage" }, "meta": { "$ref": "#/components/schemas/CuratedMeta" } }, "required": [ "data", "page", "meta" ] }, "FeedPage": { "type": "object", "description": "Bounded incremental scan. Empty pages can have a continuation. Persist sync_cursor after processing data; do not advance on schema_conformant=false.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Continue this scan: pass as `cursor` with the same limit, business_date_from and include (updated_since is ignored with a cursor). null = caught up to the watermark." }, "sync_cursor": { "type": [ "string", "null" ], "description": "Checkpoint to persist together with the processed rows. After next_cursor is null, poll later with it (every 5 to 15 minutes is enough). null only when schema_conformant is false: do not advance." }, "limit": { "type": "integer" }, "scanned": { "type": "integer" }, "watermark_at": { "type": "string", "format": "date-time", "description": "Exclusive upper bound of this scan: at least five minutes behind database time and never past the oldest in-flight transaction." } }, "required": [ "next_cursor", "sync_cursor", "limit" ] }, "CursorPage": { "type": "object", "description": "Cursor pagination. next_cursor === null is the only end-of-list signal.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` with the same filters and limit to get the next page." }, "limit": { "type": "integer" }, "total": { "type": [ "integer", "null" ], "description": "Total rows matching the filters." }, "capped": { "type": "boolean", "const": true, "description": "Present when the position limit was reached before the end of the list." } }, "required": [ "next_cursor", "limit", "total" ] }, "KeysetPage": { "type": "object", "description": "Keyset pagination (ordered by created_at, id). next_cursor === null is the only end-of-list signal; there is no position limit, so `capped` never appears.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` with the same filters and limit to get the next page." }, "limit": { "type": "integer" }, "total": { "type": [ "integer", "null" ], "description": "Total rows matching the filters (not just this page)." } }, "required": [ "next_cursor", "limit", "total" ] }, "TopNPage": { "type": "object", "description": "Top-N report: only `limit`; next_cursor is always null.", "properties": { "next_cursor": { "type": "null" }, "limit": { "type": "integer" } }, "required": [ "next_cursor", "limit" ] }, "CuratedMeta": { "type": "object", "properties": { "request_id": { "type": "string" }, "report": { "type": "string", "description": "Report name for POST /api/v1/reports/{report}; resource labels include quota, brand, topics, prompt-catalog, prompt, prompt-records, prompt-records-latest, record, record-feed, created-prompt and prompt-run." }, "duration_ms": { "type": "integer" }, "quota": { "$ref": "#/components/schemas/QuotaMeta" }, "schema_conformant": { "type": "boolean", "description": "true = data matches the documented schema exactly (every declared key present). false = the report output drifted; data is still returned as mapped (or null) — treat it as best effort." } }, "required": [ "request_id", "report", "duration_ms", "schema_conformant" ] }, "CuratedErrorMeta": { "type": "object", "properties": { "request_id": { "type": "string" }, "report": { "type": "string" }, "duration_ms": { "type": "integer" }, "quota": { "$ref": "#/components/schemas/QuotaMeta" } }, "required": [ "request_id" ] }, "QuotaMeta": { "type": "object", "description": "Billing outcome of this call. remaining / resets_at / unlimited are null on paths that never reserved credits (free reports, calls rejected before execution) — except QUOTA_EXCEEDED, which carries the live balance. Absent when the call was rejected before the report ran (schema errors, cursor errors, authentication).", "properties": { "cost": { "type": "integer", "description": "Credits actually charged for this call." }, "unlimited": { "type": [ "boolean", "null" ] }, "remaining": { "type": [ "integer", "null" ], "description": "Credits left this period; null when unlimited or unknown on this path." }, "resets_at": { "type": [ "string", "null" ], "format": "date-time" }, "charge": { "type": "string", "examples": [ "charged", "min_fee", "free", "refunded", "refund_pending", "unbilled" ], "description": "[Extensible enum] charged = normal settlement (per row, or one call for a call-priced read — including a not-found from the prompt or record detail); min_fee = minimum call fee (no data / not found from a per-row report / platform not purchased / missing locale); free = free report or endpoint; refunded / refund_pending = failed and refunded; unbilled = rejected before execution, or not metered." }, "min_fee_reason": { "type": [ "string", "null" ], "examples": [ "missing_locale", "no_data", null ], "description": "[Extensible enum]" } }, "required": [ "cost", "unlimited", "remaining", "resets_at", "charge", "min_fee_reason" ] }, "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "[Extensible enum] One of x-geoly-error-codes.", "examples": [ "INVALID_BODY", "INVALID_ARGUMENT", "INVALID_CURSOR", "IDEMPOTENCY_KEY_INVALID", "FAILED_PRECONDITION", "UNAUTHORIZED", "SUBSCRIPTION_INACTIVE", "QUOTA_EXCEEDED", "ORG_NOT_ELIGIBLE", "PLAN_LIMIT_REACHED", "API_KEY_BRAND_REQUIRED", "ORG_SELECTION_REQUIRED", "ORGANIZATION_REQUIRED", "PERMISSION_DENIED", "REPORT_NOT_FOUND", "NOT_FOUND", "METHOD_NOT_ALLOWED", "IDEMPOTENCY_KEY_REUSED", "REQUEST_IN_PROGRESS", "IDEMPOTENCY_OUTCOME_UNKNOWN", "TOOL_SURFACE_RETIRED", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "QUERY_TOO_EXPENSIVE", "RESPONSE_TOO_LARGE", "RATE_LIMITED", "GUARDED_RATE_LIMITED", "BUSY", "BUDGET_EXCEEDED", "INTERNAL_ERROR", "TOOL_TIMEOUT", "OVERLOADED", "CIRCUIT_OPEN", "TOOL_FAILED", "FEED_NOT_READY", "IDEMPOTENCY_UNAVAILABLE" ] }, "message": { "type": "string", "description": "For humans; do not parse." }, "details": { "type": "object", "description": "Stable keys: errors[] ({param, reason, allowed?, message}) on INVALID_ARGUMENT; reason; required (PERMISSION_DENIED); retry_after_seconds (429); max_bytes / actual_bytes (413 / 422); _quota (receipt); resource / id (404 NOT_FOUND of a single-resource endpoint). Other keys are informational and may change." } }, "required": [ "code", "message" ] }, "meta": { "$ref": "#/components/schemas/CuratedErrorMeta" } }, "required": [ "error", "meta" ] } } } }