> ## 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. # Get one monthly report > One month's figures as they stood when it was frozen: the headline figures, engines, what moved, the trend, losing prompts and the league. ## OpenAPI ````yaml /api-reference/openapi.json get /projects/{projectId}/reports/{reportId} 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/{reportId}: get: tags: - Monthly reports summary: Get one monthly report description: >- One month's figures as they stood when it was frozen: the headline figures, engines, what moved, the trend, losing prompts and the league. operationId: getProjectsByProjectIdReportsByReportId parameters: - name: projectId in: path required: true schema: type: string - name: reportId in: path required: true schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: report: 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)$ period: type: string pattern: ^\d{4}-\d{2}$ period_start: type: string pattern: ^\d{4}-\d{2}-\d{2}$ period_end: type: string pattern: ^\d{4}-\d{2}-\d{2}$ as_of: type: string pattern: ^\d{4}-\d{2}-\d{2}$ provisional: type: boolean month_to_date: type: boolean generated_at: type: string revoked: type: boolean description: The shared link was revoked. required: - id - period - period_start - period_end - as_of - provisional - month_to_date - generated_at - revoked additionalProperties: false project_name: type: - string - 'null' scope: anyOf: - type: object propertyNames: type: string additionalProperties: {} description: >- What the numbers cover: the window and its dates, the engines, the segments, the prompts and answers counted, and a sentence saying so. Shown beside every figure. - type: 'null' state: anyOf: - type: string enum: - empty - populated description: >- empty: no prompts in scope and no answers in the window. - type: 'null' metrics: anyOf: - type: object properties: 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. required: - visibility - share_of_voice - position - sentiment additionalProperties: false - type: 'null' rank: anyOf: - type: object properties: position: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' of: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - position - of additionalProperties: false - type: 'null' description: >- Your rank by visibility among the brands named. Null when your brand has no row. engines: type: array items: type: object properties: engine: type: - string - 'null' 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. leader: type: object properties: brand: type: object properties: id: description: Empty when nobody leads. type: - string - 'null' name: type: - string - 'null' 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. required: - brand - visibility additionalProperties: false required: - engine - visibility - leader additionalProperties: false digest: anyOf: - type: object properties: since: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: 'null' nothing_moved: type: boolean description: >- True means we looked and nothing moved outside its band, which is a finding. items: type: array items: type: object properties: headline: type: - string - 'null' figure: 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. required: - headline - figure additionalProperties: false required: - since - nothing_moved - items additionalProperties: false - type: 'null' description: Null when nothing was measured. trend: anyOf: - type: object properties: start: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: 'null' interval: anyOf: - type: string const: day - type: 'null' unit: anyOf: - type: string const: percent - type: 'null' series: type: array items: type: object properties: label: type: - string - 'null' brand_id: type: - string - 'null' own: type: boolean values: type: array items: type: - number - 'null' description: >- One per day from start; null on a day with no answers. trailing_7d: type: array items: type: - number - 'null' description: >- Visibility over the seven days ending each day. required: - label - brand_id - own - values - trailing_7d additionalProperties: false markers: type: array items: type: object properties: date: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: 'null' kind: anyOf: - type: string enum: - drift - publish - set_change - type: 'null' description: >- drift: the whole market moved; publish: you published a change; set_change: the prompts measured changed. required: - date - kind additionalProperties: false required: - start - interval - unit - series - markers additionalProperties: false - type: 'null' losing_prompts: type: array items: type: object properties: prompt_id: type: - string - 'null' text: type: - string - 'null' yours: 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. winner: type: object properties: brand: type: object properties: id: description: Empty when nobody leads. type: - string - 'null' name: type: - string - 'null' 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. required: - brand - visibility additionalProperties: false gap_points: description: Points behind the winner. type: - number - 'null' top_sources: type: array items: type: string description: The domains these answers read most. required: - prompt_id - text - yours - winner - gap_points - top_sources additionalProperties: false league: type: array items: type: object properties: 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 tracked: type: boolean description: A competitor you track. required: - id - name - own - tracked additionalProperties: false rank: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: By visibility, whatever the order of the rows. named_in: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Answers that named the brand. 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. required: - brand - rank - named_in - visibility - share_of_voice - position - sentiment additionalProperties: false required: - report - project_name - scope - state - metrics - rank - engines - digest - trend - losing_prompts - league additionalProperties: false example: report: id: 00000000-0000-4000-8000-000000000001 period: 2026-09 period_start: '2026-09-01' period_end: '2026-09-30' as_of: '2026-09-30' provisional: false month_to_date: false generated_at: '2026-11-07T09:00:00.000Z' revoked: false project_name: A scope: {} state: empty metrics: null rank: null engines: [] digest: null trend: null losing_prompts: [] league: [] '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/{reportId}" \ -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/{reportId}", 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/{reportId}", { 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.