> ## Documentation Index > Fetch the complete documentation index at: https://docs.surfais.com/llms.txt > Use this file to discover all available pages before exploring further. # List brand mentions > Flattened mention rows for an own brand. One row per finalised run unit across ALL the brand's prompts (inactive prompts' history included) with this brand's mention only — the bulk historical-pull path (`limit` up to 1000). Own brands only. A first page at that size is collected from several paging statements, so it is checked against the brand's change token before and after the walk and walked again if it moved; a token still moving after the retries is 409 `scan_in_progress` with `Retry-After` (5s) rather than a page assembled from two scan generations — expect it while a scan of the brand runs, and prefer to start a bulk walk when `last_scan_changed_at` is settled (Pagination, above). ## OpenAPI ````yaml /api-reference/openapi.json get /orgs/{orgId}/brands/{brandId}/mentions openapi: 3.1.0 info: title: Surfais API version: 1.0.0 description: >- The Surfais API gives programmatic access to the AI-visibility data Surfais measures for your brands: organisations, brands and competitors, tracked prompts, per-run results and mentions, scores, share of voice and cited sources. It can also provision brands, manage prompts and competitors, request on-demand scans, and deliver signed webhooks when a scan completes or a score or sentiment threshold is crossed. Base URL: `https://api.surfais.com/v1`. Send your API key as a Bearer token (`Authorization: Bearer sfs_live_…`). Test keys (`sfs_test_…`) are rejected by the production API. Requests and responses are JSON: a success is `{ "data": … }`, an error is `{ "error": { "code", "message" }, "request_id" }`. Guides for authentication, pagination, errors, rate limits, idempotency and webhooks are at https://docs.surfais.com/api/introduction. contact: name: Surfais support email: support@surfais.com url: https://docs.surfais.com/api/support servers: - url: https://api.surfais.com/v1 description: >- Production (the `/v1` prefix is part of the server URL; paths below are relative to it). security: - bearerKey: [] tags: - name: orgs description: Organisations reachable by the key, their usage, and the partner link. - name: brands description: Own brands (properties) and competitor rows. - name: prompts description: 'Tracked prompts: reads, CRUD and the declarative sync.' - name: results description: Finalised run-level data. - name: scores description: Persisted scores, per-market history and share of voice. - name: sources description: Cited domains. - name: scans description: On-demand scan requests. - name: webhooks description: >- Outbound event delivery: endpoints, subscriptions, deliveries (partner keys). externalDocs: description: Guides, concepts and webhooks url: https://docs.surfais.com/api/introduction paths: /orgs/{orgId}/brands/{brandId}/mentions: get: tags: - results summary: List brand mentions description: >- Flattened mention rows for an own brand. One row per finalised run unit across ALL the brand's prompts (inactive prompts' history included) with this brand's mention only — the bulk historical-pull path (`limit` up to 1000). Own brands only. A first page at that size is collected from several paging statements, so it is checked against the brand's change token before and after the walk and walked again if it moved; a token still moving after the retries is 409 `scan_in_progress` with `Retry-After` (5s) rather than a page assembled from two scan generations — expect it while a scan of the brand runs, and prefer to start a bulk walk when `last_scan_changed_at` is settled (Pagination, above). operationId: listBrandMentions parameters: - in: path name: orgId schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: >- Organisation id. Org keys: the key's own org. Partner keys: any org with an active link. Anything else is 404. required: true description: >- Organisation id. Org keys: the key's own org. Partner keys: any org with an active link. Anything else is 404. - in: path name: brandId schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: >- Brand id within the org (own brand or competitor row); 404 when not in the org. Writes that add tracking need an own (400 `validation_error` with `details[].code = "own_brand_only"`), non-archived (409 `brand_archived`) brand. required: true description: >- Brand id within the org (own brand or competitor row); 404 when not in the org. Writes that add tracking need an own (400 `validation_error` with `details[].code = "own_brand_only"`), non-archived (409 `brand_archived`) brand. - in: query name: limit schema: default: 50 description: Page size (1–1000). Default 50. type: integer minimum: 1 maximum: 1000 description: Page size (1–1000). Default 50. - in: query name: cursor schema: description: >- Opaque cursor from a previous page's `pagination.next_cursor`. It pins the walk — its sort anchor, the resolved date window and the FILTERS the first page ran under — so continue with the cursor alone: omitted filters are restored from it. Naming a different value for one of them is 400 `invalid_cursor` (`details.reason = "filter_changed"`, `details.parameter` the one that differs); start again from the first page to change a filter. type: string maxLength: 2048 description: >- Opaque cursor from a previous page's `pagination.next_cursor`. It pins the walk — its sort anchor, the resolved date window and the FILTERS the first page ran under — so continue with the cursor alone: omitted filters are restored from it. Naming a different value for one of them is 400 `invalid_cursor` (`details.reason = "filter_changed"`, `details.parameter` the one that differs); start again from the first page to change a filter. - in: query name: from schema: description: 'Window start (inclusive). Default: `to` minus 30 days.' type: string pattern: ^\d{4}-\d{2}-\d{2}$ format: date description: 'Window start (inclusive). Default: `to` minus 30 days.' - in: query name: to schema: description: >- Window end (inclusive). Default: today (UTC). Max span 366 days; `from` after `to` is 400 `validation_error`. On a paginated endpoint the resolved window is pinned by the first page and carried in the cursor — continue with the cursor alone; naming a different `from`/`to` on a continuation is 400 `invalid_cursor` (`details.reason = "window_changed"`). type: string pattern: ^\d{4}-\d{2}-\d{2}$ format: date description: >- Window end (inclusive). Default: today (UTC). Max span 366 days; `from` after `to` is 400 `validation_error`. On a paginated endpoint the resolved window is pinned by the first page and carried in the cursor — continue with the cursor alone; naming a different `from`/`to` on a continuation is 400 `invalid_cursor` (`details.reason = "window_changed"`). - in: query name: platform schema: type: string enum: - perplexity - chatgpt - gemini - claude - ai_overviews description: Scanned AI platform id. - in: query name: country schema: description: >- Mentions from runs in this market. Trimmed and upper-cased to match storage; accepts any token `Mention.country` can return. A token nothing stores returns an empty page, not an error. type: string minLength: 1 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f-\u009f]+$ description: >- Mentions from runs in this market. Trimmed and upper-cased to match storage; accepts any token `Mention.country` can return. A token nothing stores returns an empty page, not an error. responses: '200': description: Mention rows. headers: X-Request-Id: required: true description: >- Correlation id for this request; equals `request_id` in an error envelope. schema: type: string description: >- Correlation id for this request; equals `request_id` in an error envelope. X-RateLimit-Limit: required: true description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. schema: type: string description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. X-RateLimit-Remaining: required: true description: >- Requests left in the current minute window (0 on the failed-authentication 429). schema: type: string description: >- Requests left in the current minute window (0 on the failed-authentication 429). X-RateLimit-Reset: required: true description: Unix seconds at which the current minute window ends. schema: type: string description: Unix seconds at which the current minute window ends. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Mention' pagination: $ref: '#/components/schemas/Pagination' required: - data - pagination '400': description: >- `body_not_allowed` — a GET or HEAD that declared a body, refused by the intake guard BEFORE the parser, which is the only 400 a read operation reaches by that route — or `validation_error` (with `details`), `invalid_cursor`, `invalid_json` or `invalid_body`, the last two reachable only where a body is accepted at all. All are raised after authentication and the minute charge (the body is parsed only for an authenticated, admitted request), so every 400 carries the `X-RateLimit-*` trio and is metered. headers: X-Request-Id: required: true description: >- Correlation id for this request; equals `request_id` in an error envelope. schema: type: string description: >- Correlation id for this request; equals `request_id` in an error envelope. X-RateLimit-Limit: required: true description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. schema: type: string description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. X-RateLimit-Remaining: required: true description: >- Requests left in the current minute window (0 on the failed-authentication 429). schema: type: string description: >- Requests left in the current minute window (0 on the failed-authentication 429). X-RateLimit-Reset: required: true description: Unix seconds at which the current minute window ends. schema: type: string description: Unix seconds at which the current minute window ends. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: '`invalid_api_key` — uniform for every authentication failure.' headers: X-Request-Id: required: true description: >- Correlation id for this request; equals `request_id` in an error envelope. schema: type: string description: >- Correlation id for this request; equals `request_id` in an error envelope. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: >- `tier_not_entitled` — the org key's organisation left an API-entitled tier. The request is charged to the key's minute allowance (so it carries the `X-RateLimit-*` trio, and an exhausted allowance answers 429 first) and is metered. headers: X-Request-Id: required: true description: >- Correlation id for this request; equals `request_id` in an error envelope. schema: type: string description: >- Correlation id for this request; equals `request_id` in an error envelope. X-RateLimit-Limit: required: true description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. schema: type: string description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. X-RateLimit-Remaining: required: true description: >- Requests left in the current minute window (0 on the failed-authentication 429). schema: type: string description: >- Requests left in the current minute window (0 on the failed-authentication 429). X-RateLimit-Reset: required: true description: Unix seconds at which the current minute window ends. schema: type: string description: Unix seconds at which the current minute window ends. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: >- `not_found` — the org is not reachable by this key or a nested id is not in it. Raised after authentication and the minute charge, so it carries the `X-RateLimit-*` trio and is metered. headers: X-Request-Id: required: true description: >- Correlation id for this request; equals `request_id` in an error envelope. schema: type: string description: >- Correlation id for this request; equals `request_id` in an error envelope. X-RateLimit-Limit: required: true description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. schema: type: string description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. X-RateLimit-Remaining: required: true description: >- Requests left in the current minute window (0 on the failed-authentication 429). schema: type: string description: >- Requests left in the current minute window (0 on the failed-authentication 429). X-RateLimit-Reset: required: true description: Unix seconds at which the current minute window ends. schema: type: string description: Unix seconds at which the current minute window ends. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: >- `scan_in_progress` — a first page collected from several paging statements saw the brand's change token move during every walk, retries included; retry after `Retry-After` (5s). headers: X-Request-Id: required: true description: >- Correlation id for this request; equals `request_id` in an error envelope. schema: type: string description: >- Correlation id for this request; equals `request_id` in an error envelope. Retry-After: required: true description: Seconds to wait before retrying — present on every 429 and 503. schema: type: string description: >- Seconds to wait before retrying — present on every 429 and 503. X-RateLimit-Limit: required: true description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. schema: type: string description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. X-RateLimit-Remaining: required: true description: >- Requests left in the current minute window (0 on the failed-authentication 429). schema: type: string description: >- Requests left in the current minute window (0 on the failed-authentication 429). X-RateLimit-Reset: required: true description: Unix seconds at which the current minute window ends. schema: type: string description: Unix seconds at which the current minute window ends. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '413': description: >- `payload_too_large` — a JSON body over 1 MB. The body is parsed only for an authenticated, admitted request, so this carries the `X-RateLimit-*` trio and is metered. headers: X-Request-Id: required: true description: >- Correlation id for this request; equals `request_id` in an error envelope. schema: type: string description: >- Correlation id for this request; equals `request_id` in an error envelope. X-RateLimit-Limit: required: true description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. schema: type: string description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. X-RateLimit-Remaining: required: true description: >- Requests left in the current minute window (0 on the failed-authentication 429). schema: type: string description: >- Requests left in the current minute window (0 on the failed-authentication 429). X-RateLimit-Reset: required: true description: Unix seconds at which the current minute window ends. schema: type: string description: Unix seconds at which the current minute window ends. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: >- `rate_limited` (per-minute limit, or too many failed authentications from this address) or `quota_exceeded`. headers: X-Request-Id: required: true description: >- Correlation id for this request; equals `request_id` in an error envelope. schema: type: string description: >- Correlation id for this request; equals `request_id` in an error envelope. Retry-After: required: true description: Seconds to wait before retrying — present on every 429 and 503. schema: type: string description: >- Seconds to wait before retrying — present on every 429 and 503. X-RateLimit-Limit: required: true description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. schema: type: string description: >- Requests allowed per minute for this key. On a 429 `rate_limited` from the failed-authentication gate: failed attempts allowed per minute for the client address. X-RateLimit-Remaining: required: true description: >- Requests left in the current minute window (0 on the failed-authentication 429). schema: type: string description: >- Requests left in the current minute window (0 on the failed-authentication 429). X-RateLimit-Reset: required: true description: Unix seconds at which the current minute window ends. schema: type: string description: Unix seconds at which the current minute window ends. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: >- `internal_error` — quote `request_id`. A failure inside a route answers after the minute charge and carries the `X-RateLimit-*` trio; a failure before the limiter carries only `X-Request-Id`. headers: X-Request-Id: required: true description: >- Correlation id for this request; equals `request_id` in an error envelope. schema: type: string description: >- Correlation id for this request; equals `request_id` in an error envelope. X-RateLimit-Limit: description: >- Present when the failure occurred after the minute charge (inside a route); absent on a failure before the limiter. Requests allowed per minute for this key. schema: description: >- Present when the failure occurred after the minute charge (inside a route); absent on a failure before the limiter. Requests allowed per minute for this key. type: string X-RateLimit-Remaining: description: >- Present when the failure occurred after the minute charge. Requests left in the current minute window. schema: description: >- Present when the failure occurred after the minute charge. Requests left in the current minute window. type: string X-RateLimit-Reset: description: >- Present when the failure occurred after the minute charge. Unix seconds at which the current minute window ends. schema: description: >- Present when the failure occurred after the minute charge. Unix seconds at which the current minute window ends. type: string content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: >- `api_unavailable` (switched off; `Retry-After` is 60), `rate_limit_unavailable` (fail-closed limiter — its store, or a saturated failed-authentication gate; before the minute charge, so no `X-RateLimit-*` trio), or `store_unavailable` (a tenant-store call behind an authenticated request exceeded 15000 ms — raised after the minute charge, so it is counted and carries the trio). headers: X-Request-Id: required: true description: >- Correlation id for this request; equals `request_id` in an error envelope. schema: type: string description: >- Correlation id for this request; equals `request_id` in an error envelope. Retry-After: required: true description: Seconds to wait before retrying — present on every 429 and 503. schema: type: string description: >- Seconds to wait before retrying — present on every 429 and 503. X-RateLimit-Limit: description: >- Present when the failure occurred after the minute charge (inside a route); absent on a failure before the limiter. Requests allowed per minute for this key. schema: description: >- Present when the failure occurred after the minute charge (inside a route); absent on a failure before the limiter. Requests allowed per minute for this key. type: string X-RateLimit-Remaining: description: >- Present when the failure occurred after the minute charge. Requests left in the current minute window. schema: description: >- Present when the failure occurred after the minute charge. Requests left in the current minute window. type: string X-RateLimit-Reset: description: >- Present when the failure occurred after the minute charge. Unix seconds at which the current minute window ends. schema: description: >- Present when the failure occurred after the minute charge. Unix seconds at which the current minute window ends. type: string content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: Mention: type: object properties: prompt_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: UUID. run_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Calendar date, `YYYY-MM-DD` (UTC). format: date platform: type: string enum: - perplexity - chatgpt - gemini - claude - ai_overviews description: Scanned AI platform id. country: type: string description: The run's market, upper-cased — see `PromptResult.country`. finalized_at: type: string description: RFC 3339 timestamp. format: date-time mentioned: type: boolean position: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' sentiment: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' required: - prompt_id - run_date - platform - country - finalized_at - mentioned - position - sentiment Pagination: type: object properties: next_cursor: anyOf: - type: string - type: 'null' description: Opaque cursor for the next page; null on the last page. has_more: type: boolean required: - next_cursor - has_more ErrorEnvelope: type: object properties: error: type: object properties: code: type: string description: Stable machine code — see the error list in the description. message: type: string details: {} required: - code - message request_id: type: string description: Echoed in the `X-Request-Id` header. required: - error - request_id securitySchemes: bearerKey: type: http scheme: bearer bearerFormat: sfs_live_… / sfs_test_… description: >- A Surfais API key — an organisation key or a partner key. Issued by Surfais; shown once. Rotate by creating a new key, then revoking the old one. ````