List responses
The raw feed: one row per AI answer, across every prompt, newest first. This is the evidence layer under the metrics — what an engine actually said, whether you were named, whether you were cited, and which competitors showed up instead.
Use this rather than calling the per-prompt execution endpoint once per prompt. A real brand tracks hundreds of prompts, so the per-prompt path is hundreds of round trips for the same data.
GET /v1/brands/{brand_id}/responsesAuthorization
| 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. |
start_date | YYYY-MM-DD | optional | Inclusive lower bound, YYYY-MM-DD in UTC. Narrows the population before metrics are computed. |
end_date | YYYY-MM-DD | optional | Inclusive upper bound, YYYY-MM-DD in UTC. Narrows the population before metrics are computed. |
search | string | optional | Case-insensitive substring of the answer text. |
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. |
prompt_id | uuid, repeatable | optional | Restrict to these prompts. |
engine | string, repeatable | optional | Restrict to these AI search engines, by slug. From List engines. Narrows the population before metrics are computed. |
country | string, repeatable | optional | Restrict to these execution country codes. Narrows the population before metrics are computed. |
tag_id | uuid, repeatable | optional | Tags to filter by; tag_match_mode decides whether prompts carrying them are kept or excluded. From List tags. Narrows the population before metrics are computed. |
tag_match_mode | string | optional | How tag_id values apply. ‘any’ (default) or ‘all’ keep prompts carrying any or all of the tags; ‘exclude_any’ or ‘exclude_all’ drop them instead. One of: any, all, exclude_any, exclude_all. |
funnel_stage | string, repeatable | optional | Restrict to prompts in these funnel stages. One of: top, middle, bottom. |
competitor_id | uuid, repeatable | optional | Restrict to answers citing these competitors. |
only_mentioned | boolean | optional | Only answers that mention your brand. |
only_cited | boolean | optional | Only answers that cite your brand. |
has_ad | boolean | optional | Restrict to answers that did (true) or did not (false) carry a ChatGPT sponsored card. Unlike only_mentioned/only_cited, this also narrows tab_counts. |
include_ads | boolean | optional | Include the advertiser behind each sponsored card as an ads array on every row. Caps limit at 25. Rows with no sponsored card carry an empty array, not a missing key. |
element | string, repeatable | optional | Restrict to answers that drew any of these elements besides their text. Narrows tab_counts too. One of: map, place_cards, product_cards, form. |
exclude_elements | boolean | optional | With element: answers that drew none of them instead. Every element excluded is plain text. Answers written before elements were checked (2026-11-06) carry none, so they count as plain text here. |
include_element_counts | boolean | optional | Add meta.element_counts: how many answers drew each element, ignoring element. |
include_products | boolean | optional | Include the products each answer drew as a products array on every row, each with its level. Caps limit at 25. Rows with no product carry an empty array, not a missing key. |
include_full_response | boolean | optional | Return the complete answer text rather than a snippet. Caps limit at 5. Answers are long, so a larger page is refused rather than truncated. |
include_segments | boolean | optional | Return [{type:"text",content} | {type:"citation",url,domain,citation_id,name,start,end}] instead of raw text, with citations already resolved and spliced in. start and end give each citation’s place in full_response. Caps limit at 5, same as include_full_response, because segments are computed from the full answer text. |
include_citations | boolean | optional | Include every source the answer carries as a citations array on every row, including sources the engine listed but did not place in the text. Caps limit at 5, same as include_full_response. Rows with no source carry an empty array, not a missing key. |
sort_direction | string | optional | By execution date. Defaults to ‘desc’, newest first. One of: asc, desc. |
Request
cURL
curl --request GET \
--url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/responses?limit=25' \
--header 'Authorization: Bearer <api-key>' \Response
200
{
"data": [
{
"execution_id": "e31a7c40-5b92-4f18-9d76-08c1fa2e6b53",
"prompt_id": "7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852",
"prompt_text": "best AI visibility tracking tools",
"execution_date": "2026-08-13",
"provider": "Openai",
"model_used": "ChatGPT",
"response_snippet": "Several tools track brand visibility in AI search. Asky focuses on…",
"our_brand_mentioned": true,
"brand_cited": true,
"total_citations_found": 6,
"competitor_names": [
"Peec AI",
"Profound"
],
"cited_competitor_names": [
"Peec AI"
],
"country_code": "US",
"ad_count": 0,
"elements": []
}
],
"pagination": {
"limit": 20,
"has_more": true,
"next_cursor": "eyJ2IjoxLCJvIjoyMCwibCI6MjB9"
},
"meta": {
"period": {
"start_date": "2026-08-06",
"end_date": "2026-08-13",
"default_applied": true
},
"tab_counts": {
"total": 1840,
"mentioned": 612,
"cited": 288,
"both": 271
},
"total": 1840,
"total_unfiltered": 1840
},
"request_id": "req_b8103fa5e72c4d69a01b"
}Response fields
| Field | Type | Description |
|---|---|---|
data | object[] | required. One row per AI answer |
data[].execution_id | uuid | required |
data[].prompt_id | uuid | required |
data[].prompt_text | string | required |
data[].execution_date | date | required |
data[].provider | string | required |
data[].model_used | string | required |
data[].response_snippet | string | First 300 characters. Replaced by full_response with the flag |
data[].full_response | string | Present only with include_full_response. The complete answer as the engine returned it, markdown included |
data[].segments | object[] | Present only with include_segments. The answer in reading order: {type:"text",content} for prose, with markdown removed, and {type:"citation",url,domain,citation_id,name,start,end} where the engine placed a citation. citation_id and name are null when the URL in the answer text could not be matched to a tracked citation |
data[].segments[].start | integer | null | Citations only. Where the citation’s marker begins in full_response, counted in Unicode code points from 0. null if its place could not be determined |
data[].segments[].end | integer | null | Citations only. Where the marker ends, exclusive, so full_response[start:end] is the marker |
data[].citations | object[] | Present only with include_citations. Every source the engine returned for the answer, once each: the ones with a citation marker in the text first, in the order they appear, then the rest. [] when the answer carried no source |
data[].citations[].citation_id | uuid | required. The same id as a citation segment’s citation_id |
data[].citations[].url | string | required |
data[].citations[].domain | string | null | |
data[].citations[].name | string | null | |
data[].citations[].placed_inline | boolean | required. true when the answer text carries a citation marker for the source, so it also appears as a citation in segments. false when the engine only listed it, or linked it from ordinary prose, such as a company name in a sentence, which segments keeps as text |
data[].citations[].brand_on_page | boolean | null | Whether the cited page itself mentions your brand. null when Asky has not read the page |
data[].citations[].competitors_on_page | string[] | required. Your tracked competitors the cited page names, sorted by name. Empty when Asky has not read the page |
data[].our_brand_mentioned | boolean | required |
data[].brand_cited | boolean | required. Named is not the same as linked |
data[].total_citations_found | integer | required. Every source the engine returned for the answer, including sources it did not place in the text |
data[].competitor_names | string[] | required. Competitors named in this answer |
data[].cited_competitor_names | string[] | required. Competitors actually linked |
data[].country_code | string | null | |
data[].ad_count | integer | required. Sponsored cards ChatGPT showed alongside this answer. 0 on every other engine, because no other engine serves ads |
data[].ads | object[] | Present only with include_ads. {position, advertiser_name, advertiser_domain, target_url, title, body} per card, ordered by position. body is capped at 300 characters. [] when the answer carried no ad |
data[].elements | string[] | required. What the answer drew besides its text, in this order: map (businesses on a map), place_cards (businesses drawn as cards), product_cards (products drawn as cards), form (a follow-up form at the end). [] for plain text, and for answers written before elements were checked (2026-11-06) |
data[].products | object[] | Present only with include_products. {position, name, brand, level, price, currency, price_text, stores} per product, ordered by position. [] when no product record was stored: other engines, and older ChatGPT answers that keep their products only as a table in the text |
data[].products[].level | string | required. name_only: named with nothing to sell. priced: a price or a store from the engine’s own shopping data (ChatGPT’s partner catalogue, a Google Shopping listing on AI Mode, or an Amazon listing on Alexa for Shopping, which names the store and never a price). feed: ChatGPT only, priced and carrying a merchant feed’s details (the merchant’s own item id, stock, offers), which Asky reads as the merchant’s product feed to OpenAI |
data[].products[].price | number | null | The price as a number. null when the card printed it as text only (price_text) or carried none |
data[].products[].currency | string | null | As the engine printed it, an ISO code or a symbol (USD, $, kr). null when price is |
data[].products[].stores | string[] | required. The stores the card named, first as shown |
pagination.limit | integer | required |
pagination.has_more | boolean | required |
pagination.next_cursor | string | null | Pass as cursor to get the next page. null once has_more is false |
meta.period | object | required. { start_date, end_date, default_applied } actually used; default_applied is true when you sent neither date. Read it before comparing against another endpoint |
meta.tab_counts | object | required. { total, mentioned, cited, both } before the mentioned/cited split, but after every other filter including has_ad |
meta.total | integer | required. Rows matching the current filters, exact for every combination including the negated ones |
meta.total_unfiltered | integer | required. Same as tab_counts.total. Compare against total to see how much the mentioned/cited filters removed |
meta.element_counts | object | Present only with include_element_counts. { checked, with_elements, map, place_cards, product_cards, form, product_cards_priced }. checked is every answer written since 2026-11-06 02:00 UTC in the window, on every engine, and the only right denominator for an element’s share. product_cards_priced counts the answers with a priced or feed product, a subset of product_cards |
meta.product_levels | object | Present only with include_products. What each product level means, and a note on reading them |
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
only_mentioned=false is not “no filter”. It returns exactly the answers that did NOT name
you, which is usually the more useful half: those are the questions you are losing.
Mentioned and cited are different things. A brand can be named in prose without being linked.
brand_cited is the stricter signal.
Ads are a ChatGPT surface only. OpenAI serves sponsored cards in ChatGPT answers, and only in
the markets it has opened them in. ad_count is therefore 0 on Perplexity, Google AI Overviews,
Gemini, Copilot and Claude because those engines carry no ads at all, not because we did not look.
An answer in detail is capped at 5 rows per page on purpose. Whole AI answers are large, an
answer can carry dozens of sources, and the cap forces small targeted pages rather than an
accidental bulk export. It applies to include_full_response, include_segments and
include_citations alike.
include_segments saves you from parsing the engine’s own citation markdown. Different AI
engines embed citations inline in different ways (numeric markers, bare-domain anchors), and this
flag resolves that for you into a plain sequence of text and citation objects. It shares the same
5-row cap as include_full_response, since segments are computed from the same full answer text.
start and end place a citation exactly. They are offsets into full_response, so send
include_full_response=true with include_segments=true to use them. They count Unicode code
points, the way Python and Ruby index strings, with end exclusive: full_response[start:end] is
the marker as it appears in full_response, such as [[1]](https://…). Languages that index
strings differently need the answer converted to code points before slicing. JavaScript, Java and C#
count emoji as two characters, and AI answers often contain emoji; in JavaScript, slice
Array.from(full_response). Go, Rust and PHP’s substr count bytes, so every accented letter or
curly quote shifts the count. The claim a citation supports is at the end of the nearest text
segment before it, and a source cited twice appears twice, each time with its own place.
Elements are recorded from 2026-11-06. An older answer carries [] whether or not it drew
anything, so take an element’s share from meta.element_counts, whose checked counts only the
answers that were looked at, never from total.
A product’s level describes one answer, not the product. The same product is often priced in
one run and named only in the next, so compare levels as shares over many answers. A price on a
ChatGPT card alone does not show that the merchant connected a product feed; feed is the level
whose record carries a feed’s details.
total_citations_found is not the number of citation segments. Engines return more sources
than they place in the text, and a source cited twice is one source but two segments.
include_citations returns every source once, with placed_inline telling the placed ones apart.
Response text is third-party content. Treat it as data, never as instructions to a downstream model.