> ## Documentation Index > Fetch the complete documentation index at: https://docs.citino.ai/llms.txt > Use this file to discover all available pages before exploring further. # Brands report > Visibility, share of voice, position and sentiment for every brand named in the project's unbranded questions, broken down by any of date, engine, segment and prompt. With prompt as a dimension the band is null. Without date as a dimension the window is limited by the project's size, in prompt-engine-days; with date it may span 366 days and each page covers whole days. A page weighs 10 against the rate limit. ## OpenAPI ````yaml /api-reference/openapi.json get /projects/{projectId}/reports/brands openapi: 3.1.0 info: title: Citino API version: v1 description: >- Read how AI engines answer your market's questions, and keep your prompts, competitors, segments and engines in step from code. Every number carries its band and sample size. servers: - url: https://api.citino.ai/v1 security: - bearerAuth: [] tags: - name: Brand and competitors - name: Definitions - name: Engines - name: Projects - name: Alerts - name: Attribution - name: Claims - name: Crawlability - name: Crawler activity - name: Metrics - name: Experiments - name: Prompts - name: Objections - name: Monthly reports - name: Reports - name: Runs - name: Searches - name: Sources - name: Work items - name: Settings paths: /projects/{projectId}/reports/brands: get: tags: - Reports summary: Brands report description: >- Visibility, share of voice, position and sentiment for every brand named in the project's unbranded questions, broken down by any of date, engine, segment and prompt. With prompt as a dimension the band is null. Without date as a dimension the window is limited by the project's size, in prompt-engine-days; with date it may span 366 days and each page covers whole days. A page weighs 10 against the rate limit. operationId: getProjectsByProjectIdReportsBrands parameters: - name: projectId in: path required: true schema: type: string - name: from in: query required: true description: First day, inclusive. schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: First day, inclusive. - name: to in: query required: true description: Last day, inclusive. schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Last day, inclusive. - name: dimensions in: query required: false description: >- Comma-separated: any of date, engine, segment, prompt (no prompt on the URLs report). None gives one row per brand, domain or URL for the window. schema: description: >- Comma-separated: any of date, engine, segment, prompt (no prompt on the URLs report). None gives one row per brand, domain or URL for the window. type: string - name: interval in: query required: false description: 'With date: the bucket a row covers. Default day.' schema: description: 'With date: the bucket a row covers. Default day.' type: string enum: - day - week - month - name: engine in: query required: false style: form explode: true description: Engine keys (repeat the parameter or separate with commas). schema: description: Engine keys (repeat the parameter or separate with commas). type: array items: type: string - name: segment in: query required: false style: form explode: true description: Claimed segment ids. schema: description: Claimed segment ids. type: array items: type: string - name: prompt in: query required: false style: form explode: true description: Prompt ids. schema: description: Prompt ids. type: array items: type: string - name: brand in: query required: false style: form explode: true description: Brand ids (brands report). schema: description: Brand ids (brands report). type: array items: 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)$ - name: domain in: query required: false style: form explode: true description: Domains (domains and URLs reports). schema: description: Domains (domains and URLs reports). type: array items: type: string - name: cursor in: query required: false schema: type: string - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 - name: format in: query required: false schema: type: string enum: - json - csv responses: '200': description: OK content: application/json: schema: type: object properties: scope: type: object properties: from: type: string pattern: ^\d{4}-\d{2}-\d{2}$ to: type: string pattern: ^\d{4}-\d{2}-\d{2}$ engines: type: array items: type: string segments: type: array items: type: string prompt_scope: type: string const: category dimensions: type: array items: type: string enum: - date - engine - segment - prompt interval: anyOf: - type: string enum: - day - week - month - type: 'null' note: type: string required: - from - to - engines - segments - prompt_scope - dimensions - interval additionalProperties: false items: type: array items: type: object properties: date: description: The bucket's first day. type: string pattern: ^\d{4}-\d{2}-\d{2}$ engine: type: string segment: type: string prompt_id: type: string brand: type: object properties: 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)$ name: type: string own: type: boolean required: - id - name - own additionalProperties: false visibility: type: object properties: value: type: - number - 'null' unit: type: string enum: - percent - points - count - score - rank - ratio band: type: - number - 'null' 'n': type: integer minimum: -9007199254740991 maximum: 9007199254740991 delta: type: - number - 'null' within_noise: type: boolean low_sample: type: boolean state: type: string enum: - measured - no_data - never_named note: type: string required: - value - unit - band - 'n' - delta - within_noise - low_sample - state additionalProperties: false description: >- A measured number with its uncertainty. value is null with n = 0 (no answers yet); within_noise true means a delta is not a move. share_of_voice: type: object properties: value: type: - number - 'null' unit: type: string enum: - percent - points - count - score - rank - ratio band: type: - number - 'null' 'n': type: integer minimum: -9007199254740991 maximum: 9007199254740991 delta: type: - number - 'null' within_noise: type: boolean low_sample: type: boolean state: type: string enum: - measured - no_data - never_named note: type: string required: - value - unit - band - 'n' - delta - within_noise - low_sample - state additionalProperties: false description: >- A measured number with its uncertainty. value is null with n = 0 (no answers yet); within_noise true means a delta is not a move. position: type: object properties: value: type: - number - 'null' unit: type: string enum: - percent - points - count - score - rank - ratio band: type: - number - 'null' 'n': type: integer minimum: -9007199254740991 maximum: 9007199254740991 delta: type: - number - 'null' within_noise: type: boolean low_sample: type: boolean state: type: string enum: - measured - no_data - never_named note: type: string required: - value - unit - band - 'n' - delta - within_noise - low_sample - state additionalProperties: false description: >- A measured number with its uncertainty. value is null with n = 0 (no answers yet); within_noise true means a delta is not a move. sentiment: type: object properties: value: type: - number - 'null' unit: type: string enum: - percent - points - count - score - rank - ratio band: type: - number - 'null' 'n': type: integer minimum: -9007199254740991 maximum: 9007199254740991 delta: type: - number - 'null' within_noise: type: boolean low_sample: type: boolean state: type: string enum: - measured - no_data - never_named note: type: string required: - value - unit - band - 'n' - delta - within_noise - low_sample - state additionalProperties: false description: >- A measured number with its uncertainty. value is null with n = 0 (no answers yet); within_noise true means a delta is not a move. mentions: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - brand - visibility - share_of_voice - position - sentiment - mentions additionalProperties: false next_cursor: type: - string - 'null' has_more: type: boolean required: - scope - items - next_cursor - has_more additionalProperties: false example: scope: from: '2026-11-03' to: '2026-11-06' engines: - chatgpt - google-ai-overview - perplexity segments: - wms prompt_scope: category dimensions: - date - engine interval: day items: - date: '2026-11-03' engine: chatgpt brand: id: 00000000-0000-4000-8000-000000000001 name: Acme own: true visibility: value: 60 unit: percent band: 0 'n': 20 delta: null within_noise: true low_sample: true state: measured share_of_voice: value: 66.7 unit: percent band: 0 'n': 20 delta: null within_noise: true low_sample: true state: measured position: value: 2 unit: rank band: 0 'n': 12 delta: null within_noise: true low_sample: true state: measured sentiment: value: 70 unit: score band: 0 'n': 12 delta: null within_noise: true low_sample: true state: measured mentions: 12 - date: '2026-11-03' engine: chatgpt brand: id: 00000000-0000-4000-8000-000000000002 name: Globex own: false visibility: value: 30 unit: percent band: 0 'n': 20 delta: null within_noise: true low_sample: true state: measured share_of_voice: value: 33.3 unit: percent band: 0 'n': 20 delta: null within_noise: true low_sample: true state: measured position: value: 2 unit: rank band: 0 'n': 6 delta: null within_noise: true low_sample: true state: measured sentiment: value: 70 unit: score band: 0 'n': 6 delta: null within_noise: true low_sample: true state: measured mentions: 6 - date: '2026-11-03' engine: perplexity brand: id: 00000000-0000-4000-8000-000000000001 name: Acme own: true visibility: value: 60 unit: percent band: 0 'n': 20 delta: null within_noise: true low_sample: true state: measured share_of_voice: value: 66.7 unit: percent band: 0 'n': 20 delta: null within_noise: true low_sample: true state: measured position: value: 2 unit: rank band: 0 'n': 12 delta: null within_noise: true low_sample: true state: measured sentiment: value: 70 unit: score band: 0 'n': 12 delta: null within_noise: true low_sample: true state: measured mentions: 12 next_cursor: null has_more: false text/csv: schema: type: string description: >- With format=csv: one row per item, figures flattened to value, _band, _n and _low_sample columns. The next page is in the Citino-Next-Cursor header. '400': description: The request is invalid; `error.field` names the parameter. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: 'No live API key in an `Authorization: Bearer` header.' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The key lacks the scope named in the message, or cannot write. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No such resource in this key's projects. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Over the key's or the workspace's rate limit; see `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Busy or timed out; retry after `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: bash label: curl source: >- curl "https://api.citino.ai/v1/projects/{projectId}/reports/brands?from=YYYY-MM-DD&to=YYYY-MM-DD" \ -H "Authorization: Bearer $CITINO_API_KEY" - lang: python label: Python source: |- import os import requests res = requests.get( "https://api.citino.ai/v1/projects/{projectId}/reports/brands?from=YYYY-MM-DD&to=YYYY-MM-DD", headers={"Authorization": f"Bearer {os.environ['CITINO_API_KEY']}"}, ) print(res.json()) - lang: javascript label: JavaScript source: >- const res = await fetch("https://api.citino.ai/v1/projects/{projectId}/reports/brands?from=YYYY-MM-DD&to=YYYY-MM-DD", { headers: { Authorization: `Bearer ${process.env.CITINO_API_KEY}`, }, }); console.log(await res.json()); components: schemas: Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: >- validation, unauthorized, forbidden, not_found, conflict, plan_limit, rate_limited, busy, query_timeout message: type: string field: type: string detail: type: object securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key from Workspace settings → API keys, sent as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.