> ## 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 Topics > The topics buyers ask about from the latest scan's content pass in the period, each with the brand's page for it and its status, most demand first. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/topics 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}/topics: get: tags: - v1 summary: Get Topics description: >- The topics buyers ask about from the latest scan's content pass in the period, each with the brand's page for it and its status, most demand first. operationId: listTopics parameters: - in: path name: brand_id required: true schema: format: uuid title: Brand Id type: string - 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 - 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: 20 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: period required: false schema: default: 1w enum: - 1w - 4w - 12w - all title: Period type: string - in: query name: status required: false schema: anyOf: - enum: - missing - cited - falls_short - ranks_in_search - not_cited type: string - type: 'null' title: Status - in: query name: q required: false schema: anyOf: - maxLength: 200 type: string - type: 'null' title: Q - in: query name: sort required: false schema: default: demand enum: - topic - status - demand - citations - search_clicks - ai_visits - rank 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: url required: false schema: anyOf: - maxLength: 4096 type: string - type: 'null' title: Url responses: '200': content: application/json: schema: $ref: '#/components/schemas/V1Topics' 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: V1Topics: description: >- Topics buyers ask about from the latest scan's content pass in the period. properties: ai_visits_connected: title: Ai Visits Connected type: boolean cards: anyOf: - $ref: '#/components/schemas/V1TopicCards' - type: 'null' cited: anyOf: - type: integer - type: 'null' description: >- Topics whose page is cited. Null where a weekly scan it covers could not keep all its citations. title: Cited covered: title: Covered type: integer limit: title: Limit type: integer menus: anyOf: - $ref: '#/components/schemas/PromptFilters' - type: 'null' meta: $ref: '#/components/schemas/Meta' description: Normalized query and newest included scan. missing: anyOf: - type: integer - type: 'null' description: Null when the read saw too little of the site. title: Missing 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 not_read_line: anyOf: - type: string - type: 'null' title: Not Read Line offset: title: Offset type: integer period: $ref: '#/components/schemas/V1Period' search_connected: title: Search Connected type: boolean sentence: anyOf: - type: string - type: 'null' title: Sentence state: enum: - ready - awaiting_first_scan - not_measured title: State type: string statuses: items: $ref: '#/components/schemas/TopicStatusOption' title: Statuses type: array topics: items: $ref: '#/components/schemas/V1Topic' title: Topics type: array total: title: Total type: integer required: - meta - next_cursor - total - limit - offset - period - state - covered - cited - missing - topics - sentence - cards - not_read_line - statuses - menus - search_connected - ai_visits_connected title: V1Topics 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 V1TopicCards: properties: ai_visits: anyOf: - type: integer - type: 'null' title: Ai Visits cited: anyOf: - type: integer - type: 'null' title: Cited cited_change: anyOf: - $ref: '#/components/schemas/TopicCardChange' - type: 'null' covered: title: Covered type: integer covered_change: anyOf: - $ref: '#/components/schemas/TopicCardChange' - type: 'null' missing: anyOf: - type: integer - type: 'null' title: Missing missing_new: anyOf: - type: integer - type: 'null' title: Missing New total: title: Total type: integer required: - covered - total - cited - missing - missing_new - ai_visits - covered_change - cited_change title: V1TopicCards 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 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 TopicStatusOption: properties: count: title: Count type: integer label: title: Label type: string value: enum: - missing - cited - falls_short - ranks_in_search - not_cited title: Value type: string required: - value - label - count title: TopicStatusOption type: object V1Topic: properties: action: anyOf: - enum: - write - rewrite type: string - type: 'null' title: Action action_label: anyOf: - type: string - type: 'null' title: Action Label ai_visits: anyOf: - type: integer - type: 'null' title: Ai Visits citations: anyOf: - type: integer - type: 'null' description: >- The page's citations in the period; null on a missing topic. Null where a weekly scan it covers could not keep all its citations. title: Citations demand: anyOf: - type: integer - type: 'null' title: Demand id: description: The topic's key, which topics/{id} takes. title: Id type: string open_action_id: anyOf: - format: uuid type: string - type: 'null' title: Open Action Id page: anyOf: - $ref: '#/components/schemas/V1TopicPage' - type: 'null' description: The brand's page for it; null when missing. piece: anyOf: - $ref: '#/components/schemas/TopicPiece' - type: 'null' search_clicks: anyOf: - type: integer - type: 'null' title: Search Clicks status: enum: - missing - cited - falls_short - ranks_in_search - not_cited title: Status type: string status_label: title: Status Label type: string topic: title: Topic type: string why: anyOf: - type: string - type: 'null' title: Why required: - id - topic - status - page - demand - citations - search_clicks - ai_visits - status_label - action - action_label - piece - open_action_id - why title: V1Topic 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 TopicCardChange: properties: baseline: title: Baseline type: string delta: title: Delta type: integer direction: enum: - up - down - steady title: Direction type: string label: title: Label type: string required: - direction - delta - label - baseline title: TopicCardChange 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: {} V1TopicPage: properties: id: anyOf: - format: uuid type: string - type: 'null' description: The page's id in pages; null when not registered. title: Id path: title: Path type: string title: anyOf: - type: string - type: 'null' title: Title url: title: Url type: string required: - path - id - url - title title: V1TopicPage type: object TopicPiece: description: |- The piece a Missing topic already has, in the words Studio uses. `piece_id` is null while the order is still being placed: the brand's first order is dispatched before its writing profile exists, and the piece row is written once the worker has one. properties: action_id: title: Action Id type: string piece_id: anyOf: - type: string - type: 'null' title: Piece Id stage: title: Stage type: string stage_words: title: Stage Words type: string required: - action_id - piece_id - stage - stage_words title: TopicPiece 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.