> ## 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 Overview > A brand's figures over the selected period with ranges, states and change, the score's band, the latest report's status line and citation metrics, the top five rivals, the five most cited sources and the five newest open actions, the next weekly and daily scan times, the daily scans since the last weekly scan, the open action count, how many pages AI engines cannot read, what the score was read from, its move since the first weekly scan and the work verified as paying off. `with_diagnosis` adds what rivals win over the last week. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/overview 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}/overview: get: tags: - v1 summary: Get Overview description: >- A brand's figures over the selected period with ranges, states and change, the score's band, the latest report's status line and citation metrics, the top five rivals, the five most cited sources and the five newest open actions, the next weekly and daily scan times, the daily scans since the last weekly scan, the open action count, how many pages AI engines cannot read, what the score was read from, its move since the first weekly scan and the work verified as paying off. `with_diagnosis` adds what rivals win over the last week. operationId: getOverview 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: period required: false schema: default: 1w enum: - 1w - 4w - 12w - all title: Period type: string - description: >- Add `diagnosis`: the prompts and sources rivals win over the last week, and the drafts ready to answer them. in: query name: with_diagnosis required: false schema: default: false description: >- Add `diagnosis`: the prompts and sources rivals win over the last week, and the drafts ready to answer them. title: With Diagnosis type: boolean responses: '200': content: application/json: schema: $ref: '#/components/schemas/V1Overview' 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: V1Overview: properties: actions: items: $ref: '#/components/schemas/V1Action' title: Actions type: array answers_citing_you: anyOf: - $ref: '#/components/schemas/V1Count' - type: 'null' daily_scans_since_weekly: title: Daily Scans Since Weekly type: integer diagnosis: anyOf: - $ref: '#/components/schemas/V1Diagnosis' - type: 'null' description: >- What rivals win over the last week and the drafts ready to answer it; null unless `with_diagnosis`. headline: anyOf: - $ref: '#/components/schemas/V1Headline' - type: 'null' heralded_score: $ref: '#/components/schemas/V1Figure' heralded_score_band: anyOf: - type: string - type: 'null' description: >- The band of `score_bands` the Heralded Score falls in; null without a score. title: Heralded Score Band latest_read: anyOf: - $ref: '#/components/schemas/V1LatestRead' - type: 'null' mentioned: $ref: '#/components/schemas/V1Figure' meta: $ref: '#/components/schemas/Meta' description: Normalized query and newest included scan. next_daily_scan_at: anyOf: - format: date-time type: string - type: 'null' title: Next Daily Scan At next_weekly_scan_at: anyOf: - format: date-time type: string - type: 'null' title: Next Weekly Scan At open_action_count: title: Open Action Count type: integer period: $ref: '#/components/schemas/V1Period' praised: $ref: '#/components/schemas/V1Figure' readiness: anyOf: - $ref: '#/components/schemas/V1Readiness' - type: 'null' recommended: $ref: '#/components/schemas/V1Figure' rivals: items: $ref: '#/components/schemas/V1Competitor' title: Rivals type: array score_bands: description: Every Heralded Score band, lowest first. items: $ref: '#/components/schemas/ScoreBand' title: Score Bands type: array score_context: anyOf: - $ref: '#/components/schemas/V1ScoreContext' - type: 'null' description: What the latest weekly scan's score was read from; null before one. since_started: anyOf: - $ref: '#/components/schemas/V1SinceStarted' - type: 'null' description: >- The Heralded Score's move since the first weekly scan, off the period's figures; null before the first. source_citation_evidence: default: complete enum: - complete - partial - unavailable title: Source Citation Evidence type: string source_unavailable_scans: default: 0 title: Source Unavailable Scans type: integer sources: items: $ref: '#/components/schemas/V1CitedSource' title: Sources type: array sources_mentioning_you: anyOf: - $ref: '#/components/schemas/V1Count' - type: 'null' understood: $ref: '#/components/schemas/V1Figure' verified_actions: $ref: '#/components/schemas/V1VerifiedActions' required: - meta - period - heralded_score - mentioned - recommended - understood - praised - source_citation_evidence - source_unavailable_scans - latest_read - headline - answers_citing_you - sources_mentioning_you - rivals - sources - actions - next_weekly_scan_at - next_daily_scan_at - daily_scans_since_weekly - open_action_count - readiness - heralded_score_band - score_bands - score_context - since_started - verified_actions - diagnosis title: V1Overview 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 V1Action: properties: completed_at: anyOf: - format: date-time type: string - type: 'null' title: Completed At created_at: format: date-time title: Created At type: string 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 detail: anyOf: - type: string - type: 'null' title: Detail evidence: anyOf: - $ref: '#/components/schemas/TaskEvidence' - type: 'null' description: Linked prompts and rendered answer counts from the latest report. group: enum: - new - your_input - dispatched - scheduled - waiting - settled - withdrawn title: Group type: string holder: anyOf: - enum: - you - heralded - waiting type: string - type: 'null' description: >- Who holds the work: you, Heralded or a third party; null when nobody holds it. title: Holder id: format: uuid title: Id type: string kind: title: Kind type: string 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' description: First read that stopped seeing this suggestion; null when seen. 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' description: Position in the brand's proposed order; null when Heralded ranks it. title: Placed Position 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 stage: description: 'The work''s stage: observe, decide, do or verify.' enum: - observe - decide - do - verify title: Stage type: string started_at: anyOf: - format: date-time type: string - type: 'null' description: The task's first start by Heralded; null on dismissed work. title: Started At title: anyOf: - type: string - type: 'null' title: Title required: - placed_position - not_seen_since_run - evidence - note - id - title - detail - kind - member - started_at - delivered_at - paid_off_at - preview - group - holder - stage - outcome - created_at - completed_at title: V1Action type: object V1Count: description: |- A count at the latest read, what it is out of, and its share in points: null where it is out of nothing. properties: count: title: Count type: integer of: title: Of type: integer pct: anyOf: - type: integer - type: 'null' title: Pct required: - count - of - pct title: V1Count type: object V1Diagnosis: description: What rivals win over the last week, and the drafts ready to answer it. properties: drafts: $ref: '#/components/schemas/V1DiagnosisDrafts' rival_gaps: $ref: '#/components/schemas/V1RivalGaps' rival_sources: $ref: '#/components/schemas/V1RivalSources' required: - rival_gaps - rival_sources - drafts title: V1Diagnosis type: object V1Headline: properties: text: title: Text type: string required: - text title: V1Headline 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 V1LatestRead: properties: read_at: format: date-time title: Read At type: string run_number: anyOf: - type: integer - type: 'null' title: Run Number required: - read_at - run_number title: V1LatestRead 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 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 V1Readiness: description: >- The pages the readiness checks cover: every audited page and the homepage. properties: pages_blocked: title: Pages Blocked type: integer pages_checked: title: Pages Checked type: integer pages_readable: title: Pages Readable type: integer pages_unmeasured: title: Pages Unmeasured type: integer required: - pages_checked - pages_readable - pages_blocked - pages_unmeasured title: V1Readiness type: object V1Competitor: properties: domain: anyOf: - type: string - type: 'null' title: Domain heralded_score: $ref: '#/components/schemas/V1Figure' is_you: title: Is You type: boolean mentioned: $ref: '#/components/schemas/V1Figure' name: title: Name type: string rank: title: Rank type: integer recommended: $ref: '#/components/schemas/V1Figure' share_of_voice_pct: anyOf: - type: number - type: 'null' title: Share Of Voice Pct required: - name - domain - is_you - rank - heralded_score - mentioned - recommended - share_of_voice_pct title: V1Competitor 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 V1ScoreContext: description: What the latest weekly scan's Heralded Score was read from. properties: answers: title: Answers type: integer brand_name: title: Brand Name type: string engines: title: Engines type: integer first_answer_at: format: date-time title: First Answer At type: string last_answer_at: format: date-time title: Last Answer At type: string prompts: title: Prompts type: integer required: - brand_name - prompts - engines - answers - first_answer_at - last_answer_at title: V1ScoreContext type: object V1SinceStarted: description: The Heralded Score's move since the brand's first weekly scan. properties: current: anyOf: - type: integer - type: 'null' title: Current first: anyOf: - type: integer - type: 'null' description: The first weekly scan's score; null once the first scans are pooled. title: First first_report_at: format: date-time title: First Report At type: string sentence: title: Sentence type: string series: description: The score per weekly scan, oldest first. items: $ref: '#/components/schemas/V1SeriesPoint' title: Series type: array third_report_due_at: anyOf: - format: date-time type: string - type: 'null' description: >- When the third weekly scan runs, which starts the trend; null from then on. title: Third Report Due At required: - first - first_report_at - current - sentence - series - third_report_due_at title: V1SinceStarted type: object V1CitedSource: description: A cited domain and its citations over the selected period. 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 ownership: enum: - own - rival - independent title: Ownership type: string read_pages_naming_you: title: Read Pages Naming You type: integer required: - domain - group - ownership - citations - citation_share_pct - read_pages_naming_you title: V1CitedSource type: object V1VerifiedActions: description: Delivered work verification credited with a gain, newest first. properties: rows: description: The newest three. items: $ref: '#/components/schemas/V1VerifiedAction' title: Rows type: array total: title: Total type: integer required: - rows - total title: V1VerifiedActions 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 TaskEvidence: properties: answers_link: anyOf: - $ref: '#/components/schemas/AnswersLink' - type: 'null' prompts: items: $ref: '#/components/schemas/TaskPromptEvidence' title: Prompts type: array required: - prompts - answers_link title: TaskEvidence 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 V1DiagnosisDrafts: properties: draftable: description: Open work Heralded can draft now. title: Draftable type: integer ready: description: Open work whose draft or planned change waits on review. title: Ready type: integer required: - ready - draftable title: V1DiagnosisDrafts type: object V1RivalGaps: properties: count: description: Prompts a tracked rival wins and the brand does not. title: Count type: integer prompts: description: Every prompt read. title: Prompts type: integer top: description: The highest-demand of those prompts. items: type: string title: Top type: array required: - count - prompts - top title: V1RivalGaps type: object V1RivalSources: properties: count: anyOf: - type: integer - type: 'null' description: >- Third-party sources citing rivals and never the brand; null while a scan's citations are unavailable. title: Count top: items: type: string title: Top type: array unavailable_scans: title: Unavailable Scans type: integer required: - count - top - unavailable_scans title: V1RivalSources 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 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: {} V1SeriesPoint: properties: break_label: anyOf: - type: string - type: 'null' description: What changed in how this scan was measured; null where nothing did. title: Break Label completed_at: format: date-time title: Completed At type: string degraded: description: 'An engine was dropped from this scan: it measured less, not worse.' title: Degraded 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 - break_label title: V1SeriesPoint type: object V1VerifiedAction: properties: action_id: format: uuid title: Action Id type: string after: anyOf: - type: number - type: integer - type: string - type: 'null' title: After before: anyOf: - type: number - type: integer - type: string - type: 'null' title: Before completed_at: anyOf: - format: date-time type: string - type: 'null' title: Completed At credited_pts: anyOf: - type: number - type: 'null' title: Credited Pts gain: anyOf: - type: string - type: 'null' description: The gain verification credited, in a line. title: Gain happened: anyOf: - type: string - type: 'null' description: What the work did, in a line. title: Happened title: title: Title type: string required: - action_id - title - credited_pts - before - after - completed_at - happened - gain title: V1VerifiedAction type: object AnswersLink: properties: href: title: Href type: string required: - href title: AnswersLink type: object TaskPromptEvidence: properties: answer_count: title: Answer Count type: integer answers_link: $ref: '#/components/schemas/AnswersLink' named_count: title: Named Count type: integer prompt_uid: format: uuid title: Prompt Uid type: string text: anyOf: - type: string - type: 'null' title: Text required: - prompt_uid - text - named_count - answer_count - answers_link title: TaskPromptEvidence 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 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.