Skip to Content
APIEndpointsList prompts

List prompts

Prompts are the questions run against AI search engines on this brand’s behalf. Everything else on the surface is downstream of them: responses, citations, visibility.

This endpoint returns their definitions, not their performance. For visibility share, citation rate and average rank per prompt, use Prompt metrics and join on id.

GET /v1/brands/{brand_id}/prompts

Authorization

HeaderTypeRequired
AuthorizationBearer asky_sk_…required

Path parameters

ParameterTypeRequiredDescription
brand_iduuidrequiredFrom List brands

Query parameters

ParameterTypeRequiredDescription
limitintegeroptionalRows per page, 1 to 100. Defaults to 20.
cursorstringoptionalOpaque cursor from the previous response. Treat it as a token, never construct one.
is_activebooleanoptionalFilter by active state.
topic_iduuid, repeatableoptionalRestrict to these topics. From List topics. Includes the topic and its subtopics. A root topic returns everything beneath it; a subtopic returns only itself. Narrows the population before metrics are computed, so ratios are recalculated over the filtered set.
funnel_stagestring, repeatableoptionalRestrict to prompts in these funnel stages. One of: top, middle, bottom.
languagestringoptionalTwo-letter language code, e.g. en.
searchstringoptionalCase-insensitive substring of the prompt text.
volume_tierstring, repeatableoptionalRestrict to these search-demand tiers. One of: niche, low, medium, high, very_high. Prompts with no measured tier are excluded entirely while this filter is active.
prompt_typestring, repeatableoptionalRestrict to prompts of any of these Prompt Types. One of: brand, competitor, organic, unclassified. brand is shown as Branded in the app. A prompt can be brand and competitor at once; unclassified prompts have no type yet.
sortstringoptionalOrder. ‘volume’ ranks by search demand; defaults to newest first. One of: created_at, volume.

Request

curl --request GET \ --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts?limit=50' \ --header 'Authorization: Bearer <api-key>' \

Response

{ "data": [ { "id": "7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852", "prompt_text": "best AI visibility tracking tools", "is_active": true, "topic_id": "4beb0694-7c2e-488b-84c1-613738e7eaf6", "country_codes": [ "US", "GB" ], "funnel_stages": [ "middle", "bottom" ], "language": "en", "family_id": "3a9e1d70-5c2b-4f8e-b146-0d7e92c5a318", "mentions_own_brand": false, "prompt_types": ["organic"], "prompt_types_corrected": true, "automatic_prompt_types": ["competitor"], "mentioned_competitors": [ { "id": "b52e4c19-8f0a-4d3e-a7c6-91e2f04b8d75", "name": "Profound" } ], "tags": [ { "id": "1f8c2a5e-9d40-4b17-8e6a-3c05b91e7d22", "name": "Bottom funnel", "slug": "bottom-funnel", "color": "emerald" } ], "volume_tier": "medium", "volume_state": null, "difficulty_tier": "hard", "created_at": "2026-03-04T09:15:22.401Z" } ], "pagination": { "limit": 20, "has_more": true, "next_cursor": "eyJ2IjoxLCJvIjoyMCwibCI6MjB9" }, "request_id": "req_2f7b90c14ae8471da3cd" }

Response fields

FieldTypeDescription
dataobject[]required
data[].iduuidrequired
data[].prompt_textstringrequired. The question as asked
data[].is_activebooleanrequired. false for a deactivated prompt, which does not run and keeps its history
data[].topic_iduuid | nullnull for an uncategorised prompt
data[].country_codesstring[]required. Markets this prompt runs in. A prompt can target several
data[].funnel_stagesstring[]required. Multi-label, not a single stage
data[].languagestring | nullTwo-letter language of the wording, e.g. en. Derived from locale_code
data[].locale_codestring | nullRegional wording locale, e.g. en-GB. null on prompts created before languages were tracked. Codes: Markets and Languages
data[].family_iduuid | nullShared by a prompt and its language versions. Set prompt types sets a family together
data[].mentions_own_brandboolean | nullLegacy: whether Asky’s detection found the brand in the text. Use prompt_types
data[].prompt_typesstring[]required. The Prompt Type, as the app shows it: ["brand"], ["competitor"], ["brand", "competitor"], ["organic"] or ["unclassified"]. See the note below
data[].prompt_types_correctedbooleanrequired. true when someone set the type in the app, through the assistant or through the API
data[].automatic_prompt_typesstring[]Present only when prompt_types_corrected is true: Asky’s own reading of the text, in the same values
data[].mentioned_competitorsobject[]required. { id, name } of the tracked competitors Asky’s detection found in the text. A Competitor type set by someone does not name one, so this can be empty for a Competitor prompt
data[].tagsobject[]required. { id, name, slug, color }
data[].volume_tierstring | nullniche … very_high. Never a raw number
data[].volume_statestring | nullanalyzing or unknown when no tier is available yet
data[].difficulty_tierstring | nulleasy, medium or hard. Never inferred, so null when unmeasured
data[].created_attimestamptzrequired
paginationobjectrequired. See pagination
request_idstringrequired. Also returned as the x-request-id header. Quote it when contacting support

Errors

StatusCodeWhen
400invalid_requestA parameter is unknown or malformed. The message names it
401invalid_tokenThe key is missing, malformed, or does not exist
401token_expiredThe key passed its expiry date
401token_revokedThe key was revoked
404not_foundThe brand does not exist, or this key is not allowed to reach it. The two are deliberately indistinguishable
429rate_limitedOver 300 requests per minute. See the Retry-After header

Notes

Deactivated prompts are listed too. A deactivated prompt carries is_active: false and deactivated_since, keeps its history and frees its slots. Filter with is_active=true for the prompts that run.

Demand is reported as tiers, never as raw numbers. volume_tier and difficulty_tier are the same resolution the product displays, so an API answer can never disagree with what a customer sees in the app. Exact search volume and keyword difficulty are stripped from every response on this surface.

prompt_types is the branded/organic split. brand prompts name you; organic prompts describe category demand without naming you or a competitor, which is the harder and more valuable ground; competitor prompts name a tracked competitor and are comparison demand. Reporting visibility without separating them overstates how well a brand is doing. A prompt reads unclassified for a few minutes after it is added or its text changes, until detection has read it. Someone can correct a type in the app or with Set prompt types; the correction stays until the prompt’s text changes. The unclassified value exists here and in this filter only: the app’s Prompt Type filter and dashboard sections offer the other three.

topic_id includes its subtopics. A root topic returns every prompt beneath it, and a subtopic returns only its own prompts, matching the topic filter on the visibility endpoints.

Last updated on