Skip to Content
APIEndpointsList responses

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}/responses

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.
start_dateYYYY-MM-DDoptionalInclusive lower bound, YYYY-MM-DD in UTC. Narrows the population before metrics are computed.
end_dateYYYY-MM-DDoptionalInclusive upper bound, YYYY-MM-DD in UTC. Narrows the population before metrics are computed.
searchstringoptionalCase-insensitive substring of the answer text.
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.
prompt_iduuid, repeatableoptionalRestrict to these prompts.
enginestring, repeatableoptionalRestrict to these AI search engines, by slug. From List engines. Narrows the population before metrics are computed.
countrystring, repeatableoptionalRestrict to these execution country codes. Narrows the population before metrics are computed.
tag_iduuid, repeatableoptionalTags 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_modestringoptionalHow 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_stagestring, repeatableoptionalRestrict to prompts in these funnel stages. One of: top, middle, bottom.
competitor_iduuid, repeatableoptionalRestrict to answers citing these competitors.
only_mentionedbooleanoptionalOnly answers that mention your brand.
only_citedbooleanoptionalOnly answers that cite your brand.
has_adbooleanoptionalRestrict 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_adsbooleanoptionalInclude 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.
elementstring, repeatableoptionalRestrict to answers that drew any of these elements besides their text. Narrows tab_counts too. One of: map, place_cards, product_cards, form.
exclude_elementsbooleanoptionalWith 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_countsbooleanoptionalAdd meta.element_counts: how many answers drew each element, ignoring element.
include_productsbooleanoptionalInclude 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_responsebooleanoptionalReturn 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_segmentsbooleanoptionalReturn [{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_citationsbooleanoptionalInclude 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_directionstringoptionalBy execution date. Defaults to ‘desc’, newest first. One of: asc, desc.

Request

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

Response

{ "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

FieldTypeDescription
dataobject[]required. One row per AI answer
data[].execution_iduuidrequired
data[].prompt_iduuidrequired
data[].prompt_textstringrequired
data[].execution_datedaterequired
data[].providerstringrequired
data[].model_usedstringrequired
data[].response_snippetstringFirst 300 characters. Replaced by full_response with the flag
data[].full_responsestringPresent only with include_full_response. The complete answer as the engine returned it, markdown included
data[].segmentsobject[]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[].startinteger | nullCitations 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[].endinteger | nullCitations only. Where the marker ends, exclusive, so full_response[start:end] is the marker
data[].citationsobject[]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_iduuidrequired. The same id as a citation segment’s citation_id
data[].citations[].urlstringrequired
data[].citations[].domainstring | null
data[].citations[].namestring | null
data[].citations[].placed_inlinebooleanrequired. 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_pageboolean | nullWhether the cited page itself mentions your brand. null when Asky has not read the page
data[].citations[].competitors_on_pagestring[]required. Your tracked competitors the cited page names, sorted by name. Empty when Asky has not read the page
data[].our_brand_mentionedbooleanrequired
data[].brand_citedbooleanrequired. Named is not the same as linked
data[].total_citations_foundintegerrequired. Every source the engine returned for the answer, including sources it did not place in the text
data[].competitor_namesstring[]required. Competitors named in this answer
data[].cited_competitor_namesstring[]required. Competitors actually linked
data[].country_codestring | null
data[].ad_countintegerrequired. Sponsored cards ChatGPT showed alongside this answer. 0 on every other engine, because no other engine serves ads
data[].adsobject[]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[].elementsstring[]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[].productsobject[]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[].levelstringrequired. 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[].pricenumber | nullThe price as a number. null when the card printed it as text only (price_text) or carried none
data[].products[].currencystring | nullAs the engine printed it, an ISO code or a symbol (USD, $, kr). null when price is
data[].products[].storesstring[]required. The stores the card named, first as shown
pagination.limitintegerrequired
pagination.has_morebooleanrequired
pagination.next_cursorstring | nullPass as cursor to get the next page. null once has_more is false
meta.periodobjectrequired. { 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_countsobjectrequired. { total, mentioned, cited, both } before the mentioned/cited split, but after every other filter including has_ad
meta.totalintegerrequired. Rows matching the current filters, exact for every combination including the negated ones
meta.total_unfilteredintegerrequired. Same as tab_counts.total. Compare against total to see how much the mentioned/cited filters removed
meta.element_countsobjectPresent 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_levelsobjectPresent only with include_products. What each product level means, and a note on reading them
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

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.

Last updated on