> ## 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 Prompt Suggestions > Discover's ranked recommendations with provenance, form and demand. `segment` selects the segment label for `best_to_track`. Demand names its source; unknown demand stays null. Measurement names the keyword market, language and current coverage.keyword_research and coverage.search_volume availability; a row overrides it where its measurement differs. Unavailable keyword research does not fall back to older suggestions. Reads use stored facts and free catalogs, never a paid provider. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/prompt-suggestions 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}/prompt-suggestions: get: tags: - v1 summary: Get Prompt Suggestions description: >- Discover's ranked recommendations with provenance, form and demand. `segment` selects the segment label for `best_to_track`. Demand names its source; unknown demand stays null. Measurement names the keyword market, language and current coverage.keyword_research and coverage.search_volume availability; a row overrides it where its measurement differs. Unavailable keyword research does not fall back to older suggestions. Reads use stored facts and free catalogs, never a paid provider. operationId: listPromptSuggestions 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: 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: segment required: false schema: anyOf: - maxLength: 200 type: string - type: 'null' title: Segment responses: '200': content: application/json: schema: $ref: '#/components/schemas/V1PromptSuggestions' 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: V1PromptSuggestions: properties: items: items: $ref: '#/components/schemas/V1PromptSuggestion' title: Items type: array limit: title: Limit type: integer measurement: anyOf: - $ref: '#/components/schemas/KeywordMeasurement' - 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 offset: title: Offset type: integer pool: $ref: '#/components/schemas/V1DiscoverPool' sources: $ref: '#/components/schemas/V1DiscoverSources' state: enum: - ready - awaiting_first_scan title: State type: string suggestions: items: $ref: '#/components/schemas/V1PickerSuggestion' title: Suggestions type: array total: title: Total type: integer unavailable: items: $ref: '#/components/schemas/V1DiscoverUnavailable' title: Unavailable type: array required: - meta - next_cursor - total - limit - offset - measurement - state - pool - sources - unavailable - items - suggestions title: V1PromptSuggestions 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 V1PromptSuggestion: properties: best_to_track: title: Best To Track type: boolean brand_comparison: title: Brand Comparison type: boolean clicks: anyOf: - type: integer - type: 'null' title: Clicks demand: $ref: '#/components/schemas/V1DiscoverDemand' form: enum: - short - conversational - persona - comparison - alternatives title: Form type: string form_label: title: Form Label type: string impressions: anyOf: - type: integer - type: 'null' title: Impressions intent: anyOf: - type: string - type: 'null' title: Intent measurement: anyOf: - $ref: '#/components/schemas/KeywordMeasurement' - type: 'null' position: anyOf: - type: number - type: 'null' title: Position proposed_type: anyOf: - type: string - type: 'null' title: Proposed Type reason: title: Reason type: string search_volume: anyOf: - type: integer - type: 'null' title: Search Volume sources: items: enum: - search_console - heralded - rivals - engines type: string title: Sources type: array text: title: Text type: string topic: anyOf: - type: string - type: 'null' title: Topic tracked_segments: items: type: string title: Tracked Segments type: array why: items: $ref: '#/components/schemas/V1DiscoverWhy' title: Why type: array required: - measurement - text - sources - why - reason - search_volume - impressions - clicks - position - topic - intent - proposed_type - tracked_segments - best_to_track - form - form_label - demand - brand_comparison title: V1PromptSuggestion type: object KeywordMeasurement: properties: country: anyOf: - type: string - type: 'null' description: Requested country; null means Global. title: Country coverage: $ref: '#/components/schemas/KeywordCoverage' description: >- Current catalog availability, not a historical snapshot. Unknown means no catalog is available. language: description: Product language code, independent of vendor aliases. title: Language type: string measured_country: description: Country actually targeted; Global uses US. title: Measured Country type: string required: - country - measured_country - language - coverage title: KeywordMeasurement 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 V1DiscoverPool: properties: cap: anyOf: - type: integer - type: 'null' title: Cap used: title: Used type: integer required: - used - cap title: V1DiscoverPool type: object V1DiscoverSources: properties: heralded: enum: - ready - awaiting_first_scan - running - failed - no_suggestions title: Heralded type: string heralded_read_at: anyOf: - format: date-time type: string - type: 'null' title: Heralded Read At search_console: enum: - connected - not_connected - reconnect_required title: Search Console type: string required: - search_console - heralded - heralded_read_at title: V1DiscoverSources type: object V1PickerSuggestion: properties: intent_label: anyOf: - type: string - type: 'null' title: Intent Label measurement: anyOf: - $ref: '#/components/schemas/KeywordMeasurement' - type: 'null' reason: title: Reason type: string text: title: Text type: string required: - measurement - text - intent_label - reason title: V1PickerSuggestion type: object V1DiscoverUnavailable: properties: measurement: anyOf: - $ref: '#/components/schemas/KeywordMeasurement' - type: 'null' provider: title: Provider type: string reason: title: Reason type: string required: - measurement - provider - reason title: V1DiscoverUnavailable 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 V1DiscoverDemand: properties: label: title: Label type: string source: anyOf: - enum: - search_console - keyword_volume - engine_searches type: string - type: 'null' title: Source value: anyOf: - type: integer - type: 'null' title: Value required: - value - source - label title: V1DiscoverDemand type: object V1DiscoverWhy: properties: key: enum: - search_console - search_demand - rivals_lead - open_ground - rival_pattern - engine_searches title: Key type: string label: title: Label type: string required: - key - label title: V1DiscoverWhy type: object KeywordCoverage: properties: keyword_research: description: Availability of discovery and difficulty. enum: - available - unavailable - unknown title: Keyword Research type: string search_volume: description: Availability of monthly keyword search volume. enum: - available - unavailable - unknown title: Search Volume type: string required: - keyword_research - search_volume title: KeywordCoverage 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: {} 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.