> ## Documentation Index > Fetch the complete documentation index at: https://docs.geoly.ai/llms.txt > Use this file to discover all available pages before exploring further. # 品牌榜 > 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). ## OpenAPI ````yaml api-reference/openapi.json POST /api/v1/reports/brand-board 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. Stability: 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. Envelope: `{ 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). Pagination: 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. Errors 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}). Billing: 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. The 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). paths: /api/v1/reports/brand-board: post: tags: - Reports 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). operationId: runBrandBoardReport 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' security: - bearerAuth: [] components: schemas: 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 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 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 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: {} 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 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 securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key from Settings → Developer → API keys (prefix geom_). Each key is bound to one brand. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.