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}/promptsAuthorization
| Header | Type | Required |
|---|---|---|
Authorization | Bearer asky_sk_… | required |
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
brand_id | uuid | required | From List brands |
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Rows per page, 1 to 100. Defaults to 20. |
cursor | string | optional | Opaque cursor from the previous response. Treat it as a token, never construct one. |
is_active | boolean | optional | Filter by active state. |
topic_id | uuid, repeatable | optional | Restrict 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_stage | string, repeatable | optional | Restrict to prompts in these funnel stages. One of: top, middle, bottom. |
language | string | optional | Two-letter language code, e.g. en. |
search | string | optional | Case-insensitive substring of the prompt text. |
volume_tier | string, repeatable | optional | Restrict 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_type | string, repeatable | optional | Restrict 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. |
sort | string | optional | Order. ‘volume’ ranks by search demand; defaults to newest first. One of: created_at, volume. |
Request
cURL
curl --request GET \
--url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/prompts?limit=50' \
--header 'Authorization: Bearer <api-key>' \Response
200
{
"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
| Field | Type | Description |
|---|---|---|
data | object[] | required |
data[].id | uuid | required |
data[].prompt_text | string | required. The question as asked |
data[].is_active | boolean | required. false for a deactivated prompt, which does not run and keeps its history |
data[].topic_id | uuid | null | null for an uncategorised prompt |
data[].country_codes | string[] | required. Markets this prompt runs in. A prompt can target several |
data[].funnel_stages | string[] | required. Multi-label, not a single stage |
data[].language | string | null | Two-letter language of the wording, e.g. en. Derived from locale_code |
data[].locale_code | string | null | Regional wording locale, e.g. en-GB. null on prompts created before languages were tracked. Codes: Markets and Languages |
data[].family_id | uuid | null | Shared by a prompt and its language versions. Set prompt types sets a family together |
data[].mentions_own_brand | boolean | null | Legacy: whether Asky’s detection found the brand in the text. Use prompt_types |
data[].prompt_types | string[] | required. The Prompt Type, as the app shows it: ["brand"], ["competitor"], ["brand", "competitor"], ["organic"] or ["unclassified"]. See the note below |
data[].prompt_types_corrected | boolean | required. true when someone set the type in the app, through the assistant or through the API |
data[].automatic_prompt_types | string[] | Present only when prompt_types_corrected is true: Asky’s own reading of the text, in the same values |
data[].mentioned_competitors | object[] | 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[].tags | object[] | required. { id, name, slug, color } |
data[].volume_tier | string | null | niche … very_high. Never a raw number |
data[].volume_state | string | null | analyzing or unknown when no tier is available yet |
data[].difficulty_tier | string | null | easy, medium or hard. Never inferred, so null when unmeasured |
data[].created_at | timestamptz | required |
pagination | object | required. See pagination |
request_id | string | required. Also returned as the x-request-id header. Quote it when contacting support |
Errors
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A parameter is unknown or malformed. The message names it |
| 401 | invalid_token | The key is missing, malformed, or does not exist |
| 401 | token_expired | The key passed its expiry date |
| 401 | token_revoked | The key was revoked |
| 404 | not_found | The brand does not exist, or this key is not allowed to reach it. The two are deliberately indistinguishable |
| 429 | rate_limited | Over 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.