> ## Documentation Index > Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Scores > All five figures over the selected period, with ranges, states, change and trends, over the answers the engine, type, intent, topic, segment and prompt filters keep, and per group under `group_by`. `include` also returns the Engines table or pane. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/scores openapi: 3.1.0 info: description: >- Read-only access to one organization's brands, as the member who created the API key. Each key may make 120 requests a minute. Every error is an RFC 9457 problem (`application/problem+json`) whose `code` names it. summary: Read your brands' AI visibility in Heralded. title: Heralded API version: '1' servers: - url: https://api.heralded.ai security: [] paths: /v1/brands/{brand_id}/scores: get: tags: - v1 summary: Get Scores description: >- All five figures over the selected period, with ranges, states, change and trends, over the answers the engine, type, intent, topic, segment and prompt filters keep, and per group under `group_by`. `include` also returns the Engines table or pane. operationId: getScores parameters: - in: path name: brand_id required: true schema: format: uuid title: Brand Id type: string - description: Include only scans up to this completed scan id. in: query name: as_of required: false schema: anyOf: - format: uuid type: string - type: 'null' description: Include only scans up to this completed scan id. title: As Of - in: query name: limit required: false schema: default: 10 maximum: 100 minimum: 1 title: Limit type: integer - in: query name: offset required: false schema: default: 0 minimum: 0 title: Offset type: integer - in: query name: cursor required: false schema: anyOf: - maxLength: 4096 type: string - type: 'null' title: Cursor - in: query name: engine required: false schema: anyOf: - enum: - perplexity - gemini - openai - google_aio - ai_mode - copilot - claude type: string - type: 'null' title: Engine - in: query name: prompt required: false schema: anyOf: - format: uuid type: string - type: 'null' title: Prompt - in: query name: type required: false schema: anyOf: - enum: - organic - brand_specific - competitor_comparison type: string - type: 'null' title: Type - in: query name: intent required: false schema: anyOf: - enum: - educational - problem - comparison - transactional type: string - type: 'null' title: Intent - in: query name: topic required: false schema: anyOf: - format: uuid type: string - type: 'null' title: Topic - in: query name: segment required: false schema: anyOf: - type: string - type: 'null' title: Segment - in: query name: period required: false schema: default: 1w enum: - 1w - 4w - 12w - all title: Period type: string - in: query name: with_panes required: false schema: default: false title: With Panes type: boolean - in: query name: figure_only required: false schema: default: false title: Figure Only type: boolean - description: >- Also state the figures per engine, intent, prompt type, topic, segment, prompt or competitor, under the same period and filters. in: query name: group_by required: false schema: anyOf: - enum: - engine - intent - type - topic - segment - prompt - competitor type: string - type: 'null' description: >- Also state the figures per engine, intent, prompt type, topic, segment, prompt or competitor, under the same period and filters. title: Group By - description: >- Also return the Engines table, or one engine's pane with the engine filter. in: query name: include required: false schema: anyOf: - enum: - engines - engine type: string - type: 'null' description: >- Also return the Engines table, or one engine's pane with the engine filter. title: Include - in: query name: sort required: false schema: default: score enum: - engine - score - trend - mentioned - recommended - understood - praised - answers title: Sort type: string - in: query name: direction required: false schema: anyOf: - enum: - asc - desc type: string - type: 'null' title: Direction - in: query name: with_menus required: false schema: default: false title: With Menus type: boolean - in: query name: with_cards required: false schema: default: false title: With Cards type: boolean - in: query name: you required: false schema: anyOf: - enum: - named - not_named type: string - type: 'null' title: You - in: query name: topic_id required: false schema: anyOf: - maxLength: 100 type: string - type: 'null' title: Topic Id responses: '200': content: application/json: schema: $ref: '#/components/schemas/V1Scores' description: Successful Response '400': content: application/problem+json: example: code: invalid_cursor detail: The cursor is invalid or belongs to a different query. instance: example-request-id status: 400 title: Bad Request type: about:blank schema: $ref: '#/components/schemas/Problem' description: The cursor is invalid or belongs to a different query. '401': content: application/problem+json: example: code: invalid_token detail: >- The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired. instance: example-request-id status: 401 title: Unauthorized type: about:blank schema: $ref: '#/components/schemas/Problem' description: No API key, or one that is unknown, revoked or expired. headers: WWW-Authenticate: schema: example: Bearer type: string '404': content: application/problem+json: example: code: not_found detail: Nothing here that this API key can read. instance: example-request-id status: 404 title: Not Found type: about:blank schema: $ref: '#/components/schemas/Problem' description: No such brand or answer, or the key's owner cannot read it. '409': content: application/problem+json: example: code: workspace_archived detail: The API key's organization is archived. instance: example-request-id status: 409 title: Conflict type: about:blank schema: $ref: '#/components/schemas/Problem' description: The API key's organization is archived. '422': content: application/problem+json: example: code: invalid_request detail: The request's parameters are invalid; `errors` names each one. errors: - loc: - query - limit msg: Input should be less than or equal to 100 type: less_than_equal instance: example-request-id status: 422 title: Unprocessable Content type: about:blank schema: $ref: '#/components/schemas/ValidationProblem' description: A path or query parameter is invalid. '429': content: application/problem+json: example: code: rate_limited detail: >- This caller is past its requests for the minute. Retry after the seconds in Retry-After. instance: example-request-id rate_limit: limit: 120 remaining: 0 reset: 60 window: 60 status: 429 title: Too Many Requests type: about:blank schema: $ref: '#/components/schemas/RateLimitProblem' description: The API key made more than 120 requests in the minute. headers: Retry-After: description: Seconds until the key may call again. schema: example: 60 type: integer security: - apiKey: [] components: schemas: V1Scores: properties: cards: anyOf: - items: $ref: '#/components/schemas/HomeFigure' type: array - type: 'null' title: Cards engine: anyOf: - $ref: '#/components/schemas/V1EnginePane' - type: 'null' engines: anyOf: - $ref: '#/components/schemas/EnginesPage' - type: 'null' groups: anyOf: - items: $ref: '#/components/schemas/V1ScoreRow' type: array - type: 'null' title: Groups heralded_score: $ref: '#/components/schemas/V1Figure' mentioned: $ref: '#/components/schemas/V1Figure' menus: anyOf: - $ref: '#/components/schemas/PromptFilters' - type: 'null' meta: $ref: '#/components/schemas/Meta' description: Normalized query and newest included scan. next_cursor: anyOf: - type: string - type: 'null' description: >- Pass as cursor with the same query to read the next page; null at the end. title: Next Cursor pane_headline: anyOf: - $ref: '#/components/schemas/V1PaneHeadline' - type: 'null' pane_prompts: items: $ref: '#/components/schemas/PerceptionPromptRow' title: Pane Prompts type: array pane_rivals: items: $ref: '#/components/schemas/RivalAxes' title: Pane Rivals type: array panes: anyOf: - items: $ref: '#/components/schemas/V1AxisPane' type: array - type: 'null' title: Panes period: $ref: '#/components/schemas/V1Period' praised: $ref: '#/components/schemas/V1Figure' recommended: $ref: '#/components/schemas/V1Figure' understood: $ref: '#/components/schemas/V1Figure' required: - meta - next_cursor - period - heralded_score - mentioned - recommended - understood - praised - groups - panes - pane_prompts - pane_rivals - pane_headline - engines - engine - menus - cards title: V1Scores type: object Problem: description: |- An RFC 9457 problem. `type` is always `about:blank`, so `title` is the status's name, and `code` is what a client branches on. properties: code: title: Code type: string detail: title: Detail type: string instance: default: '' title: Instance type: string status: title: Status type: integer title: title: Title type: string type: const: about:blank default: about:blank title: Type type: string required: - type - title - status - detail - code - instance title: Problem type: object ValidationProblem: properties: code: title: Code type: string detail: title: Detail type: string errors: items: $ref: '#/components/schemas/ValidationIssue' title: Errors type: array instance: default: '' title: Instance type: string status: title: Status type: integer title: title: Title type: string type: const: about:blank default: about:blank title: Type type: string required: - type - title - status - detail - code - instance - errors title: ValidationProblem type: object RateLimitProblem: properties: code: title: Code type: string detail: title: Detail type: string instance: default: '' title: Instance type: string rate_limit: $ref: '#/components/schemas/RateLimitValues' status: title: Status type: integer title: title: Title type: string type: const: about:blank default: about:blank title: Type type: string required: - type - title - status - detail - code - instance - rate_limit title: RateLimitProblem type: object HomeFigure: description: One figure as Home's cards, and the Prompts cards after them, read it. properties: change: $ref: '#/components/schemas/HomeChange' key: title: Key type: string series: $ref: '#/components/schemas/MetricSeries' value: anyOf: - type: integer - type: 'null' title: Value required: - key - value - series - change title: HomeFigure type: object V1EnginePane: properties: answers: title: Answers type: integer cadence_note: anyOf: - type: string - type: 'null' title: Cadence Note change: $ref: '#/components/schemas/PromptTrend' competitors: items: $ref: '#/components/schemas/PromptCompetitor' title: Competitors type: array competitors_limit: title: Competitors Limit type: integer competitors_offset: title: Competitors Offset type: integer competitors_total: title: Competitors Total type: integer display_name: title: Display Name type: string engine_id: title: Engine Id type: string figures: $ref: '#/components/schemas/Figures' filters: $ref: '#/components/schemas/FigureFilters' marks: items: $ref: '#/components/schemas/ScoreMark' title: Marks type: array period: $ref: '#/components/schemas/PeriodDescriptor' prompts: title: Prompts type: integer score: $ref: '#/components/schemas/ScoreMark' score_label: title: Score Label type: string score_trend: items: $ref: '#/components/schemas/FigurePoint' title: Score Trend type: array sentence: title: Sentence type: string sources: items: $ref: '#/components/schemas/V1EngineSource' title: Sources type: array strongest_prompts: items: $ref: '#/components/schemas/EnginePrompt' title: Strongest Prompts type: array tiles: items: $ref: '#/components/schemas/PromptTile' title: Tiles type: array weakest_prompts: items: $ref: '#/components/schemas/EnginePrompt' title: Weakest Prompts type: array required: - engine_id - display_name - cadence_note - figures - score - marks - change - answers - prompts - period - filters - score_label - sentence - score_trend - tiles - competitors - competitors_total - competitors_limit - competitors_offset - strongest_prompts - weakest_prompts - sources title: V1EnginePane type: object EnginesPage: properties: filters: $ref: '#/components/schemas/FigureFilters' limit: title: Limit type: integer menus: anyOf: - $ref: '#/components/schemas/PromptFilters' - type: 'null' offset: title: Offset type: integer period: $ref: '#/components/schemas/PeriodDescriptor' rows: items: $ref: '#/components/schemas/EngineRow' title: Rows type: array sentence: anyOf: - type: string - type: 'null' title: Sentence total: title: Total type: integer required: - period - filters - sentence - rows - total - limit - offset - menus title: EnginesPage type: object V1ScoreRow: properties: group: $ref: '#/components/schemas/V1ScoreGroup' heralded_score: $ref: '#/components/schemas/V1Figure' mentioned: $ref: '#/components/schemas/V1Figure' praised: $ref: '#/components/schemas/V1Figure' recommended: $ref: '#/components/schemas/V1Figure' understood: $ref: '#/components/schemas/V1Figure' required: - group - heralded_score - mentioned - recommended - understood - praised title: V1ScoreRow type: object V1Figure: properties: answers: title: Answers type: integer change: anyOf: - $ref: '#/components/schemas/V1Change' - type: 'null' denominator: anyOf: - type: integer - type: 'null' title: Denominator high: anyOf: - type: integer - type: 'null' title: High low: anyOf: - type: integer - type: 'null' title: Low numerator: anyOf: - type: number - type: 'null' title: Numerator state: enum: - measured - too_few_answers - calibrating - first_report - not_comparable - not_measured title: State type: string trend: items: $ref: '#/components/schemas/V1TrendPoint' title: Trend type: array value: anyOf: - type: integer - type: 'null' title: Value required: - value - low - high - numerator - denominator - answers - state - change - trend title: V1Figure type: object PromptFilters: description: >- What the toolbar's four menus offer, counted over every tracked prompt rather than over the page (PR-4). A menu built from one page of ten would hide the segment the eleventh row is in. properties: intents: items: $ref: '#/components/schemas/PromptFilterOption' title: Intents type: array segments: items: $ref: '#/components/schemas/PromptFilterOption' title: Segments type: array topics: items: $ref: '#/components/schemas/PromptFilterOption' title: Topics type: array types: items: $ref: '#/components/schemas/PromptFilterOption' title: Types type: array required: - segments - types - intents - topics title: PromptFilters type: object Meta: properties: data_as_of: anyOf: - $ref: '#/components/schemas/DataAsOf' - type: 'null' query: additionalProperties: $ref: '#/components/schemas/JsonValue' title: Query type: object required: - query - data_as_of title: Meta type: object V1PaneHeadline: properties: describes_you: anyOf: - $ref: '#/components/schemas/DescribesYou' - type: 'null' heralded_score: anyOf: - $ref: '#/components/schemas/HeraldedScore' - type: 'null' mentioned: anyOf: - $ref: '#/components/schemas/RankedRate' - type: 'null' recommended: anyOf: - $ref: '#/components/schemas/RankedRate' - type: 'null' required: - heralded_score - mentioned - recommended - describes_you title: V1PaneHeadline type: object PerceptionPromptRow: description: |- A prompt every screen that lists prompts refers to by key, so the thirty-four rows are serialised once rather than once per axis. properties: cells: items: $ref: '#/components/schemas/PerceptionPromptCell' title: Cells type: array intent: anyOf: - type: string - type: 'null' title: Intent key: title: Key type: string prompt_type: anyOf: - type: string - type: 'null' title: Prompt Type query_id: title: Query Id type: string search_volume: anyOf: - type: integer - type: 'null' title: Search Volume text: title: Text type: string required: - key - query_id - text - intent - prompt_type - search_volume - cells title: PerceptionPromptRow type: object RivalAxes: description: >- One brand on the rival block of every pane but Understood (#2358): the three axes a rival can be read on, over the same answers the brand was read on, so a rival's 40% and the brand's 60% are shares of one population. Understood has no rival figure — there is no rival profile to match an answer against — so `axes` carries three, not four. Serialised once under `Perception.rivals` and read by every pane, the way the prompt rows are; each pane picks its own axis off the row. properties: axes: items: $ref: '#/components/schemas/PerceptionAxisFigure' title: Axes type: array brand_key: title: Brand Key type: string brand_name: title: Brand Name type: string domain: anyOf: - type: string - type: 'null' title: Domain heralded_score: anyOf: - type: integer - type: 'null' title: Heralded Score is_subject: title: Is Subject type: boolean mentioned: anyOf: - type: integer - type: 'null' title: Mentioned recommended: anyOf: - type: integer - type: 'null' title: Recommended required: - brand_key - brand_name - domain - is_subject - axes - heralded_score - mentioned - recommended title: RivalAxes type: object V1AxisPane: properties: actions: items: $ref: '#/components/schemas/V1PaneAction' title: Actions type: array answers_link: anyOf: - $ref: '#/components/schemas/AnswersLink' - type: 'null' axis: title: Axis type: string by_engine: items: $ref: '#/components/schemas/EngineAxisRow' title: By Engine type: array by_intent: anyOf: - items: $ref: '#/components/schemas/IntentAxisRow' type: array - type: 'null' title: By Intent engines: items: $ref: '#/components/schemas/EngineScreen' title: Engines type: array figure: anyOf: - $ref: '#/components/schemas/Figure' - type: 'null' intents: anyOf: - items: $ref: '#/components/schemas/IntentScreen' type: array - type: 'null' title: Intents label: title: Label type: string measures: items: $ref: '#/components/schemas/Measure' title: Measures type: array negative_quotes: items: $ref: '#/components/schemas/AxisQuote' title: Negative Quotes type: array recommended: anyOf: - $ref: '#/components/schemas/RecommendedPane' - type: 'null' state: default: '' title: State type: string tone_split: anyOf: - $ref: '#/components/schemas/ToneSplit' - type: 'null' trend: anyOf: - items: $ref: '#/components/schemas/PerceptionSeriesPoint' type: array - type: 'null' title: Trend trend_note: anyOf: - type: string - type: 'null' title: Trend Note required: - answers_link - axis - label - state - measures - trend - trend_note - by_engine - by_intent - engines - intents - recommended - actions - figure - tone_split - negative_quotes title: V1AxisPane type: object V1Period: properties: excluded_reports: title: Excluded Reports type: integer first_answer_at: anyOf: - format: date-time type: string - type: 'null' title: First Answer At last_answer_at: anyOf: - format: date-time type: string - type: 'null' title: Last Answer At preset: enum: - 1w - 4w - 12w - all title: Preset type: string reports: title: Reports type: integer required: - preset - reports - first_answer_at - last_answer_at - excluded_reports title: V1Period type: object ValidationIssue: properties: loc: items: anyOf: - type: string - type: integer title: Loc type: array msg: title: Msg type: string type: title: Type type: string required: - loc - msg - type title: ValidationIssue type: object RateLimitValues: properties: limit: title: Limit type: integer remaining: title: Remaining type: integer reset: title: Reset type: integer window: title: Window type: integer required: - limit - window - remaining - reset title: RateLimitValues type: object HomeChange: properties: baseline: anyOf: - type: string - type: 'null' title: Baseline delta: anyOf: - type: number - type: 'null' title: Delta state: enum: - up - down - steady - calibrating - first_report title: State type: string required: - state - delta - baseline title: HomeChange type: object MetricSeries: properties: introduced_at_run: anyOf: - type: integer - type: 'null' title: Introduced At Run metric: title: Metric type: string points: items: $ref: '#/components/schemas/SeriesPoint' title: Points type: array required: - metric - introduced_at_run - points title: MetricSeries type: object PromptTrend: description: A score's change, as the Trend column and the pane state it. properties: delta: anyOf: - type: integer - type: 'null' title: Delta label: anyOf: - type: string - type: 'null' title: Label state: enum: - up - down - steady - not_comparable - calibrating - new - none title: State type: string required: - state - delta - label title: PromptTrend type: object PromptCompetitor: description: >- A brand the prompt's answers name, of the brand and its tracked competitors, on the same answers as the prompt's own figures. `answers` counts those answers, which a figure's denominator may leave some of out, as Mentioned does a Brand-type prompt's. properties: answers: default: 0 title: Answers type: integer brand_key: title: Brand Key type: string brand_name: title: Brand Name type: string domain: anyOf: - type: string - type: 'null' title: Domain heralded_score: $ref: '#/components/schemas/Figure' is_you: title: Is You type: boolean mentioned: $ref: '#/components/schemas/Figure' recommended: $ref: '#/components/schemas/Figure' trend: $ref: '#/components/schemas/PromptTrend' required: - brand_key - brand_name - is_you - domain - answers - heralded_score - mentioned - recommended - trend title: PromptCompetitor type: object Figures: properties: heralded_score: $ref: '#/components/schemas/Figure' mentioned: $ref: '#/components/schemas/Figure' praised: $ref: '#/components/schemas/Figure' recommended: $ref: '#/components/schemas/Figure' understood: $ref: '#/components/schemas/Figure' required: - heralded_score - mentioned - recommended - understood - praised title: Figures type: object FigureFilters: properties: engine: anyOf: - enum: - perplexity - gemini - openai - google_aio - ai_mode - copilot - claude type: string - type: 'null' title: Engine intent: anyOf: - enum: - educational - problem - comparison - transactional type: string - type: 'null' title: Intent prompt: anyOf: - format: uuid type: string - type: 'null' title: Prompt segment: anyOf: - type: string - type: 'null' title: Segment topic: anyOf: - format: uuid type: string - type: 'null' title: Topic type: anyOf: - enum: - organic - brand_specific - competitor_comparison type: string - type: 'null' title: Type required: - engine - prompt - type - intent - topic - segment title: FigureFilters type: object ScoreMark: description: >- A score or figure from the figures read, with the band it is coloured by (#4259). `key` is the engine or the figure measured. `band` is the Heralded Score's band for the value, so a mark and a score read on one scale, and "Not measured" where no value is served, which includes a group under the minimum of answers. On a score, `answers` counts every answer the period read under the filters, including those a figure's own denominator leaves out. properties: answer_read_id: anyOf: - type: string - type: 'null' title: Answer Read Id answers: title: Answers type: integer band: title: Band type: string key: title: Key type: string label: title: Label type: string state: enum: - measured - too_few_answers - calibrating - first_report - not_comparable - not_measured title: State type: string tooltip: anyOf: - type: string - type: 'null' title: Tooltip value: anyOf: - type: integer - type: 'null' title: Value required: - key - label - value - state - band - answers - tooltip - answer_read_id title: ScoreMark type: object PeriodDescriptor: properties: excluded_reports: title: Excluded Reports type: integer first_answer_at: anyOf: - format: date-time type: string - type: 'null' title: First Answer At last_answer_at: anyOf: - format: date-time type: string - type: 'null' title: Last Answer At preset: enum: - 1w - 4w - 12w - all title: Preset type: string reports: title: Reports type: integer required: - preset - reports - first_answer_at - last_answer_at - excluded_reports title: PeriodDescriptor type: object FigurePoint: properties: answers: title: Answers type: integer at: format: date-time title: At type: string break_label: anyOf: - type: string - type: 'null' title: Break Label breaks: items: $ref: '#/components/schemas/KeyChange' title: Breaks type: array high: anyOf: - type: integer - type: 'null' title: High key: $ref: '#/components/schemas/ComparabilityKey' low: anyOf: - type: integer - type: 'null' title: Low scan_id: format: uuid title: Scan Id type: string state: enum: - measured - too_few_answers - calibrating - first_report - not_comparable - not_measured title: State type: string value: anyOf: - type: integer - type: 'null' title: Value required: - scan_id - at - value - low - high - answers - state - key - breaks - break_label title: FigurePoint type: object V1EngineSource: properties: citation_share_pct: anyOf: - type: integer - type: 'null' title: Citation Share Pct citations: title: Citations type: integer domain: title: Domain type: string group: enum: - own - rival - review - editorial - community - vendor - other title: Group type: string names_you: anyOf: - type: boolean - type: 'null' title: Names You ownership: enum: - own - rival - independent title: Ownership type: string read_pages_naming_you: title: Read Pages Naming You type: integer relationship_label: anyOf: - type: string - type: 'null' title: Relationship Label type_label: title: Type Label type: string required: - domain - group - ownership - citations - citation_share_pct - read_pages_naming_you - names_you - type_label - relationship_label title: V1EngineSource type: object EnginePrompt: properties: change: $ref: '#/components/schemas/PromptTrend' prompt_uid: format: uuid title: Prompt Uid type: string score: $ref: '#/components/schemas/ScoreMark' text: title: Text type: string required: - prompt_uid - text - score - change title: EnginePrompt type: object PromptTile: properties: answer_count: title: Answer Count type: integer denominator: title: Denominator type: integer explorer_filter: additionalProperties: type: string title: Explorer Filter type: object numerator: title: Numerator type: number pct: anyOf: - type: integer - type: 'null' title: Pct unit_label: title: Unit Label type: string required: - pct - numerator - denominator - unit_label - explorer_filter - answer_count title: PromptTile type: object EngineRow: properties: answers: title: Answers type: integer cadence_note: anyOf: - type: string - type: 'null' title: Cadence Note change: $ref: '#/components/schemas/PromptTrend' display_name: title: Display Name type: string engine_id: title: Engine Id type: string figures: $ref: '#/components/schemas/Figures' marks: items: $ref: '#/components/schemas/ScoreMark' title: Marks type: array prompts: title: Prompts type: integer score: $ref: '#/components/schemas/ScoreMark' required: - engine_id - display_name - cadence_note - figures - score - marks - change - answers - prompts title: EngineRow type: object V1ScoreGroup: description: |- What one group of `groups` is: the value of the dimension `group_by` names, the others null. A competitor group names the brand, and `is_you` marks the brand's own. properties: brand_name: anyOf: - type: string - type: 'null' title: Brand Name competitor: anyOf: - type: string - type: 'null' title: Competitor engine: anyOf: - type: string - type: 'null' title: Engine intent: anyOf: - type: string - type: 'null' title: Intent is_you: default: false title: Is You type: boolean prompt: anyOf: - format: uuid type: string - type: 'null' title: Prompt segment: anyOf: - type: string - type: 'null' title: Segment topic: anyOf: - format: uuid type: string - type: 'null' title: Topic type: anyOf: - type: string - type: 'null' title: Type required: - engine - intent - type - topic - segment - prompt - competitor - brand_name - is_you title: V1ScoreGroup type: object V1Change: properties: baseline: $ref: '#/components/schemas/V1Baseline' cells_unpaired: title: Cells Unpaired type: integer delta: anyOf: - type: number - type: 'null' title: Delta direction: enum: - up - down - steady title: Direction type: string high: anyOf: - type: number - type: 'null' title: High low: anyOf: - type: number - type: 'null' title: Low real: title: Real type: boolean required: - delta - low - high - real - direction - baseline - cells_unpaired title: V1Change type: object V1TrendPoint: properties: answers: title: Answers type: integer at: format: date-time title: At type: string break_label: anyOf: - type: string - type: 'null' title: Break Label high: anyOf: - type: integer - type: 'null' title: High low: anyOf: - type: integer - type: 'null' title: Low state: enum: - measured - too_few_answers - calibrating - first_report - not_comparable - not_measured title: State type: string value: anyOf: - type: integer - type: 'null' title: Value required: - at - value - low - high - answers - state - break_label title: V1TrendPoint type: object PromptFilterOption: properties: count: title: Count type: integer label: title: Label type: string value: title: Value type: string required: - value - label - count title: PromptFilterOption type: object DataAsOf: properties: completed_at: format: date-time title: Completed At type: string id: format: uuid title: Id type: string required: - id - completed_at title: DataAsOf type: object JsonValue: {} DescribesYou: description: |- Understood and Praised over the answers naming the brand that a full read interpreted. `n` counts those answers; each share states its own. properties: 'n': title: 'N' type: integer praised: anyOf: - $ref: '#/components/schemas/DescribedShare' - type: 'null' understood: anyOf: - $ref: '#/components/schemas/DescribedShare' - type: 'null' required: - understood - praised - 'n' title: DescribesYou type: object HeraldedScore: description: >- The Heralded Score in points, its 95% range, and the answers read, with the band it falls in and every band in order, so a surface names and draws the band from the payload. properties: answers: title: Answers type: integer band: readOnly: true title: Band type: string bands: items: $ref: '#/components/schemas/ScoreBand' readOnly: true title: Bands type: array change: anyOf: - $ref: '#/components/schemas/PairedChange' - type: 'null' high: title: High type: integer low: title: Low type: integer value: title: Value type: integer required: - value - low - high - answers - change - band - bands title: HeraldedScore type: object RankedRate: description: >- Mentioned or Recommended: the rate in points with its 95% range, the k of n answers it counts, and the brand's place among the rivals `cohort` names: those the run scored (`run`) or those tracked today (`roster`). Brands on the same figure share a place. `rank` is None where no answer counted the brand, because that place would be shared with every brand no answer counted; `rank_of` counts the brand and every rival measured. properties: change: anyOf: - $ref: '#/components/schemas/PairedChange' - type: 'null' cohort: enum: - run - roster title: Cohort type: string high: title: High type: integer k: title: K type: integer low: title: Low type: integer 'n': title: 'N' type: integer rank: anyOf: - type: integer - type: 'null' title: Rank rank_of: title: Rank Of type: integer value: title: Value type: integer required: - value - low - high - k - 'n' - rank - rank_of - cohort - change title: RankedRate type: object PerceptionPromptCell: description: >- One prompt on one engine, with the four states that read (D32, D37). `praised` is the axis reading — whether this answer frames the brand positively — and `sentiment` is the framing itself. The page needs both: the mood a cell shows has three states, and a neutral read and a critical one are both `praised: false`. properties: answer_read_id: anyOf: - type: string - type: 'null' title: Answer Read Id cited: title: Cited type: boolean engine_id: title: Engine Id type: string icon_states: $ref: '#/components/schemas/IconStates' readOnly: true mentioned: anyOf: - type: boolean - type: 'null' title: Mentioned praised: anyOf: - type: boolean - type: 'null' title: Praised recommended: anyOf: - type: boolean - type: 'null' title: Recommended sentiment: anyOf: - type: string - type: 'null' title: Sentiment strength: anyOf: - type: string - type: 'null' title: Strength strength_label: anyOf: - type: string - type: 'null' readOnly: true title: Strength Label understood: anyOf: - type: integer - type: 'null' title: Understood required: - engine_id - strength - mentioned - understood - recommended - praised - sentiment - cited - answer_read_id - strength_label - icon_states title: PerceptionPromptCell type: object PerceptionAxisFigure: description: One axis's weighted percentage, range and measured population. properties: axis: title: Axis type: string denominator: title: Denominator type: integer figure: $ref: '#/components/schemas/MetricFigure' readOnly: true high: anyOf: - type: integer - type: 'null' title: High label: title: Label type: string low: anyOf: - type: integer - type: 'null' title: Low measured: title: Measured type: boolean numerator: title: Numerator type: number value: anyOf: - type: integer - type: 'null' title: Value required: - axis - label - value - numerator - denominator - measured - low - high - figure title: PerceptionAxisFigure type: object V1PaneAction: properties: assignee: anyOf: - $ref: '#/components/schemas/AssigneeResponse' - type: 'null' blocked_owner: anyOf: - type: string - type: 'null' title: Blocked Owner check_again_on: anyOf: - format: date type: string - type: 'null' title: Check Again On completed_at: anyOf: - format: date-time type: string - type: 'null' title: Completed At created_at: format: date-time title: Created At type: string credit_cost: title: Credit Cost type: integer delivered_at: anyOf: - format: date-time type: string - type: 'null' description: >- When the result went live, was sent or was published. Null on dismissed work. title: Delivered At demand: title: Demand type: string detail: anyOf: - type: string - type: 'null' title: Detail dispatchable: title: Dispatchable type: boolean draft_in_flight: anyOf: - enum: - drafting - redrafting type: string - type: 'null' title: Draft In Flight expected_impact_pts: anyOf: - type: integer - type: 'null' title: Expected Impact Pts gate: anyOf: - enum: - approval - review type: string - type: 'null' title: Gate group: enum: - new - your_input - dispatched - scheduled - waiting - settled - withdrawn title: Group type: string holder: anyOf: - enum: - you - heralded - waiting type: string - type: 'null' title: Holder id: format: uuid title: Id type: string impact_scale: anyOf: - type: string - type: 'null' title: Impact Scale intent_bucket: anyOf: - type: string - type: 'null' title: Intent Bucket job: $ref: '#/components/schemas/JobResponse' kind: readOnly: true title: Kind type: string looks_resolved_evidence: anyOf: - additionalProperties: true type: object - type: 'null' title: Looks Resolved Evidence member: anyOf: - enum: - writer - publicist - engineer - analyst type: string - type: 'null' description: The responsible team member; null for setup and prompt tracking. title: Member not_seen_since_run: anyOf: - type: integer - type: 'null' title: Not Seen Since Run note: anyOf: - $ref: '#/components/schemas/TaskNote' - type: 'null' description: Task explanation with a live job step. outcome: anyOf: - enum: - verified_up - no_move - not_measured - dismissed type: string - type: 'null' title: Outcome paid_off_at: anyOf: - format: date-time type: string - type: 'null' description: >- When verification credited a positive measured gain. Null on dismissed work. title: Paid Off At placed_position: anyOf: - type: integer - type: 'null' title: Placed Position platform: default: false title: Platform type: boolean preview: anyOf: - type: string - type: 'null' description: >- Up to 400 characters of draft opening, email recipient and subject, or planned change while waiting on you. title: Preview primary_verb: anyOf: - enum: - dispatch - take - done - defer - dismiss - confirm - reject - restore - block - unblock - reopen type: string - const: review type: string - type: 'null' title: Primary Verb progress: anyOf: - $ref: '#/components/schemas/WorkProgressResponse' - type: 'null' prompt_movement: anyOf: - type: string - type: 'null' title: Prompt Movement prompt_slot_cost: title: Prompt Slot Cost type: integer repeat: anyOf: - enum: - daily - weekly - thrice_weekly type: string - type: 'null' title: Repeat return_group: anyOf: - enum: - new - your_input - dispatched - scheduled - waiting - settled - withdrawn type: string - type: 'null' title: Return Group route: enum: - home - actions - prompts - engines - market - sources - content - perception - audit readOnly: true title: Route type: string run_state: anyOf: - enum: - scheduled - running - done - skipped - failed - stopped type: string - type: 'null' title: Run State scheduled_at: anyOf: - format: date-time type: string - type: 'null' title: Scheduled At scheduled_for: anyOf: - format: date type: string - type: 'null' title: Scheduled For secondary_verbs: items: enum: - dispatch - take - done - defer - dismiss - confirm - reject - restore - block - unblock - reopen type: string title: Secondary Verbs type: array segment: title: Segment type: string settled_at: anyOf: - format: date-time type: string - type: 'null' title: Settled At setup_link: anyOf: - $ref: '#/components/schemas/SetupLink' - type: 'null' stage: enum: - observe - decide - do - verify title: Stage type: string started_at: anyOf: - format: date-time type: string - type: 'null' description: The first time Heralded started this task. Null on dismissed work. title: Started At state: enum: - new - accepted - in_progress - blocked - looks_resolved - done - verified_no_move - deferred - dismissed - withdrawn title: State type: string target_entity: title: Target Entity type: string target_type: anyOf: - type: string - type: 'null' title: Target Type title: anyOf: - type: string - type: 'null' title: Title tracked_domain_id: format: uuid title: Tracked Domain Id type: string updated_at: format: date-time title: Updated At type: string verified_impact_pts: anyOf: - type: number - type: 'null' title: Verified Impact Pts required: - id - tracked_domain_id - target_entity - target_type - segment - title - detail - state - group - holder - stage - demand - member - started_at - delivered_at - paid_off_at - preview - outcome - gate - settled_at - impact_scale - expected_impact_pts - verified_impact_pts - prompt_movement - blocked_owner - check_again_on - scheduled_for - scheduled_at - repeat - progress - platform - run_state - assignee - intent_bucket - looks_resolved_evidence - not_seen_since_run - placed_position - completed_at - created_at - updated_at - primary_verb - setup_link - secondary_verbs - return_group - job - note - credit_cost - dispatchable - draft_in_flight - prompt_slot_cost - route - kind title: V1PaneAction type: object AnswersLink: properties: href: title: Href type: string required: - href title: AnswersLink type: object EngineAxisRow: description: |- An engine on an axis pane's By engine list; opens the engine screen. The percentage travels with the population it is a share of, because two engines on the same list rarely read the same number of answers and 50% of two is not 50% of twenty (BR-1). properties: axis: default: '' title: Axis type: string denominator: title: Denominator type: integer display: title: Display type: string engine_id: title: Engine Id type: string figure: $ref: '#/components/schemas/MetricFigure' readOnly: true numerator: title: Numerator type: number value: anyOf: - type: integer - type: 'null' title: Value required: - engine_id - value - display - numerator - denominator - axis - figure title: EngineAxisRow type: object IntentAxisRow: description: An intent on an axis pane's By intent list; opens the intent screen. properties: axis: default: '' title: Axis type: string denominator: title: Denominator type: integer display: title: Display type: string figure: $ref: '#/components/schemas/MetricFigure' readOnly: true intent: title: Intent type: string numerator: title: Numerator type: number prompts: title: Prompts type: integer value: anyOf: - type: integer - type: 'null' title: Value required: - intent - value - display - prompts - numerator - denominator - axis - figure title: IntentAxisRow type: object EngineScreen: description: That axis's measures for one engine, and the prompts it read (BR-5). properties: answers_link: anyOf: - $ref: '#/components/schemas/AnswersLink' - type: 'null' engine_id: title: Engine Id type: string measures: items: $ref: '#/components/schemas/Measure' title: Measures type: array prompt_order: items: type: string title: Prompt Order type: array state: title: State type: string trend: anyOf: - items: $ref: '#/components/schemas/PerceptionSeriesPoint' type: array - type: 'null' title: Trend required: - answers_link - engine_id - state - measures - trend - prompt_order title: EngineScreen type: object Figure: properties: answers: title: Answers type: integer change: anyOf: - $ref: '#/components/schemas/FigureChange' - type: 'null' denominator: anyOf: - type: integer - type: 'null' title: Denominator high: anyOf: - type: integer - type: 'null' title: High low: anyOf: - type: integer - type: 'null' title: Low numerator: anyOf: - type: number - type: 'null' title: Numerator state: enum: - measured - too_few_answers - calibrating - first_report - not_comparable - not_measured title: State type: string trend: items: $ref: '#/components/schemas/FigurePoint' title: Trend type: array value: anyOf: - type: integer - type: 'null' title: Value required: - value - low - high - numerator - denominator - answers - state - change - trend title: Figure type: object IntentScreen: description: The prompts of one intent, with the two axes that slice by it. properties: intent: title: Intent type: string mentioned: anyOf: - type: integer - type: 'null' title: Mentioned prompt_order: items: type: string title: Prompt Order type: array prompts: title: Prompts type: integer prompts_total: title: Prompts Total type: integer recommended: anyOf: - type: integer - type: 'null' title: Recommended search_volume: anyOf: - type: integer - type: 'null' title: Search Volume required: - intent - prompts - prompts_total - mentioned - recommended - search_volume - prompt_order title: IntentScreen type: object Measure: description: |- One row of a quadrant's or a pane's measure block (BR-3). `kind` says which bar draws it: `pct` is the 0-to-100 bar, `five` the 1-to-5 segmented scale. `display` is the words beside the bar, composed here so a figure reads the same on the quadrant, in the pane and on an engine screen. properties: denominator: anyOf: - type: integer - type: 'null' title: Denominator display: title: Display type: string figure: anyOf: - $ref: '#/components/schemas/MetricFigure' - type: 'null' readOnly: true key: title: Key type: string kind: enum: - pct - five title: Kind type: string label: title: Label type: string numerator: anyOf: - type: number - type: 'null' title: Numerator value: anyOf: - type: number - type: 'null' title: Value required: - key - label - kind - value - display - numerator - denominator - figure title: Measure type: object AxisQuote: properties: answer_read_id: title: Answer Read Id type: string engine_id: title: Engine Id type: string prompt_text: title: Prompt Text type: string quote: title: Quote type: string required: - quote - engine_id - prompt_text - answer_read_id title: AxisQuote type: object RecommendedPane: description: |- What only Recommended's pane shows (BR-4): who wins the period's answers, and the prompts a win is out of. properties: prompts_total: title: Prompts Total type: integer who_wins: items: $ref: '#/components/schemas/StandingRow' title: Who Wins type: array required: - who_wins - prompts_total title: RecommendedPane type: object ToneSplit: description: |- The answers naming the brand, split three ways. `neutral` is the stored valence the page calls balanced: no valuation, or one favouring no side. properties: named: title: Named type: integer negative: title: Negative type: integer neutral: title: Neutral type: integer positive: title: Positive type: integer required: - positive - neutral - negative - named title: ToneSplit type: object PerceptionSeriesPoint: properties: at: title: At type: string break_label: anyOf: - type: string - type: 'null' title: Break Label breaks: default: [] items: $ref: '#/components/schemas/KeyChange' title: Breaks type: array key: anyOf: - $ref: '#/components/schemas/ComparabilityKey' - type: 'null' measured_domain: anyOf: - type: string - type: 'null' title: Measured Domain prompts_changed: default: false title: Prompts Changed type: boolean value: anyOf: - type: integer - type: 'null' title: Value required: - at - value - measured_domain - key - breaks - break_label - prompts_changed title: PerceptionSeriesPoint type: object SeriesPoint: properties: break_label: anyOf: - type: string - type: 'null' title: Break Label breaks: default: [] items: $ref: '#/components/schemas/KeyChange' title: Breaks type: array completed_at: title: Completed At type: string degraded: default: false title: Degraded type: boolean key: anyOf: - $ref: '#/components/schemas/ComparabilityKey' - type: 'null' measured_domain: anyOf: - type: string - type: 'null' title: Measured Domain prompts_changed: default: false title: Prompts Changed type: boolean run_number: title: Run Number type: integer value: anyOf: - type: number - type: integer - type: 'null' title: Value required: - run_number - completed_at - value - degraded - measured_domain - key - breaks - break_label - prompts_changed title: SeriesPoint type: object KeyChange: description: One part of the instrument that changed between two reads. properties: added: default: [] items: type: string title: Added type: array part: enum: - engines - market - score_version - answer_pack_version title: Part type: string removed: default: [] items: type: string title: Removed type: array value: anyOf: - type: string - type: 'null' title: Value required: - part - added - removed - value title: KeyChange type: object ComparabilityKey: description: |- The instrument one read was taken with. A part that cannot be told is None, and a None part never breaks a series: a run whose answers the retention sweep took no longer says which engines it asked. properties: answer_pack_version: anyOf: - type: integer - type: 'null' title: Answer Pack Version engines: anyOf: - items: type: string type: array - type: 'null' title: Engines markets: additionalProperties: type: string default: {} title: Markets type: object passes: anyOf: - type: integer - type: 'null' title: Passes score_version: title: Score Version type: string required: - engines - markets - score_version - answer_pack_version - passes title: ComparabilityKey type: object V1Baseline: properties: first_answer_at: anyOf: - format: date-time type: string - type: 'null' title: First Answer At last_answer_at: anyOf: - format: date-time type: string - type: 'null' title: Last Answer At reports: title: Reports type: integer required: - reports - first_answer_at - last_answer_at title: V1Baseline type: object DescribedShare: description: >- A weighted share of answers naming the brand, its range and answer count. properties: change: anyOf: - $ref: '#/components/schemas/PairedChange' - type: 'null' high: anyOf: - type: integer - type: 'null' title: High low: anyOf: - type: integer - type: 'null' title: Low 'n': title: 'N' type: integer value: title: Value type: integer required: - value - low - high - 'n' - change title: DescribedShare type: object ScoreBand: description: 'One band of the Heralded Score: its word and the scores it spans.' properties: high: title: High type: integer label: title: Label type: string low: title: Low type: integer required: - label - low - high title: ScoreBand type: object PairedChange: description: |- A figure's change over the selected window, in points, with its 95% range (`app.scans.scoring.axes.change_payload`). `real` is whether the paired test over the prompt × engine cells both reads measured says it moved; a surface announces only a real change. properties: delta: title: Delta type: number high: title: High type: number low: title: Low type: number real: title: Real type: boolean required: - delta - low - high - real title: PairedChange type: object IconStates: description: Each axis as the icon a row draws for it. properties: mentioned: enum: - 'yes' - partial - 'no' - not_measured title: Mentioned type: string praised: enum: - 'yes' - partial - 'no' - not_measured title: Praised type: string recommended: enum: - 'yes' - partial - 'no' - not_measured title: Recommended type: string understood: enum: - 'yes' - partial - 'no' - not_measured title: Understood type: string required: - mentioned - understood - recommended - praised title: IconStates type: object MetricFigure: properties: denominator: title: Denominator type: integer explorer_filter: additionalProperties: type: string title: Explorer Filter type: object numerator: title: Numerator type: number pct: anyOf: - type: integer - type: 'null' title: Pct unit_label: title: Unit Label type: string required: - pct - numerator - denominator - unit_label - explorer_filter title: MetricFigure type: object AssigneeResponse: properties: id: format: uuid title: Id type: string initials: title: Initials type: string name: title: Name type: string required: - id - name - initials title: AssigneeResponse type: object JobResponse: description: |- What this row's task is as a job (#2429): every stage, where it stands, what happens next and what the button does. Composed per kind by `app.actions.jobs.describe_job`; no surface keeps a second table. properties: act_label: title: Act Label type: string control: enum: - dispatch - act - take title: Control type: string current: anyOf: - type: string - type: 'null' title: Current kind: title: Kind type: string next_step: anyOf: - type: string - type: 'null' title: Next Step primary_label: anyOf: - type: string - type: 'null' title: Primary Label runs_steps: anyOf: - type: boolean - type: 'null' title: Runs Steps stages: items: $ref: '#/components/schemas/JobStageResponse' title: Stages type: array step: anyOf: - $ref: '#/components/schemas/JobStepResponse' - type: 'null' stopped_at: anyOf: - type: string - type: 'null' title: Stopped At required: - kind - stages - current - stopped_at - next_step - control - primary_label - act_label - runs_steps - step title: JobResponse type: object TaskNote: properties: how_well_know: title: How Well Know type: string short_form: title: Short Form type: string what_i_need_from_you: title: What I Need From You type: string what_ill_do: title: What Ill Do type: string whats_happening: title: Whats Happening type: string why_it_matters: title: Why It Matters type: string required: - whats_happening - why_it_matters - what_ill_do - what_i_need_from_you - how_well_know - short_form title: TaskNote type: object WorkProgressResponse: description: |- How far an executing read has got (#2446): engines answered of the engines asked. The words are the row's; the pips are the client's. properties: done: title: Done type: integer total: title: Total type: integer unit: title: Unit type: string required: - done - total - unit title: WorkProgressResponse type: object SetupLink: properties: href: title: Href type: string label: title: Label type: string required: - label - href title: SetupLink type: object FigureChange: properties: baseline: $ref: '#/components/schemas/ComparisonPeriod' cells_unpaired: title: Cells Unpaired type: integer delta: anyOf: - type: number - type: 'null' title: Delta direction: enum: - up - down - steady title: Direction type: string high: anyOf: - type: number - type: 'null' title: High low: anyOf: - type: number - type: 'null' title: Low real: title: Real type: boolean required: - delta - low - high - real - direction - baseline - cells_unpaired title: FigureChange type: object StandingRow: description: One brand on the Who wins list (DATA-3). properties: answers: title: Answers type: integer brand_key: title: Brand Key type: string brand_name: title: Brand Name type: string decided_answers: title: Decided Answers type: integer is_subject: title: Is Subject type: boolean named: title: Named type: integer picked: title: Picked type: integer picked_answers: title: Picked Answers type: integer prompts_won: title: Prompts Won type: integer required: - brand_key - brand_name - is_subject - named - picked - picked_answers - decided_answers - answers - prompts_won title: StandingRow type: object JobStageResponse: properties: doer: enum: - heralded - member - watch title: Doer type: string done_at: anyOf: - format: date-time type: string - type: 'null' title: Done At key: title: Key type: string label: title: Label type: string line: title: Line type: string required: - key - label - line - doer - done_at title: JobStageResponse type: object JobStepResponse: description: |- One stage the member may run alone where the area would run the whole job: `hold_at_gate` on the dispatch request stops it at the approval gate (#2429). properties: hold_at_gate: title: Hold At Gate type: boolean label: title: Label type: string required: - label - hold_at_gate title: JobStepResponse type: object ComparisonPeriod: properties: first_answer_at: anyOf: - format: date-time type: string - type: 'null' title: First Answer At last_answer_at: anyOf: - format: date-time type: string - type: 'null' title: Last Answer At reports: title: Reports type: integer required: - reports - first_answer_at - last_answer_at title: ComparisonPeriod type: object securitySchemes: apiKey: description: 'An API key, sent as `Authorization: Bearer hrld_...`.' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.