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

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	Restrict to prompts carrying these tags. From List tags. Narrows the population before metrics are computed.
`tag_match_mode`	`string`	optional	How to combine tag_id values. Defaults to ‘any’. One of: `any`, `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.
`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}]` instead of raw text, with citations already resolved and spliced in. Caps `limit` at 5, same as `include_full_response` — segments are computed from the full answer text.
`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>' \

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/responses?limit=25"
 
headers = {"Authorization": "Bearer <api-key>"}
 
response = requests.get(url, headers=headers)
 
print(response.text)

JavaScript


const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer <api-key>'}
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/responses?limit=25', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

PHP


<?php
 
$curl = curl_init();
 
curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/responses?limit=25",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <api-key>"
  ],
]);
 
$response = curl_exec($curl);
$err = curl_error($curl);
 
curl_close($curl);
 
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Go


package main
 
import (
    "fmt"
    "net/http"
    "io"
)
 
func main() {
 
    url := "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/responses?limit=25"
 
    req, _ := http.NewRequest("GET", url, nil)
 
    req.Header.Add("Authorization", "Bearer <api-key>")
 
    res, _ := http.DefaultClient.Do(req)
 
    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)
 
    fmt.Println(string(body))
 
}

Ruby


require 'uri'
require 'net/http'
 
url = URI("https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/responses?limit=25")
 
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
 
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <api-key>'
 
response = http.request(request)
puts response.read_body

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-13T04:12:07.882Z",
      "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"
    }
  ],
  "pagination": {
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJ2IjoxLCJvIjoyMCwibCI6MjB9"
  },
  "meta": {
    "period": {
      "start_date": "2026-08-06",
      "end_date": "2026-08-13"
    },
    "tab_counts": {
      "total": 1840,
      "mentioned": 612,
      "cited": 288,
      "both": 271
    },
    "total": 1840,
    "total_unfiltered": 1840
  },
  "request_id": "req_b8103fa5e72c4d69a01b"
}

401


{
  "error": {
    "code": "token_expired",
    "message": "This API key has expired. Roll it in Settings to get a replacement.",
    "request_id": "req_8f21c0aa47b1490d2e63"
  }
}

404


{
  "error": {
    "code": "not_found",
    "message": "Not found.",
    "request_id": "req_5b0e77d213a94f6a8ce1"
  }
}

429


{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 24 seconds.",
    "request_id": "req_31c9ba7f0e5d4a118cc2"
  }
}

Response fields

Field	Type	Description
`data.period`	`object`	required. `{ start_date, end_date }` actually used. Read it before comparing against another endpoint
`data.responses`	`object[]`	required
`data.responses[].execution_id`	`uuid`	required
`data.responses[].prompt_id`	`uuid`	required
`data.responses[].prompt_text`	`string`	required
`data.responses[].execution_date`	`timestamptz`	required
`data.responses[].provider`	`string`	required
`data.responses[].model_used`	`string`	required
`data.responses[].response_snippet`	`string`	First 300 characters. Replaced by `full_response` with the flag
`data.responses[].segments`	`object[]`	Present only with `include_segments`. Each entry is `{type:"text",content}` or `{type:"citation",url,domain,citation_id,name}` — `citation_id`/`name` are `null` when the URL in the answer text could not be matched to a tracked citation
`data.responses[].our_brand_mentioned`	`boolean`	required
`data.responses[].brand_cited`	`boolean`	required. Named is not the same as linked
`data.responses[].total_citations_found`	`integer`	required
`data.responses[].competitor_names`	`string[]`	required. Competitors named in this answer
`data.responses[].cited_competitor_names`	`string[]`	required. Competitors actually linked
`data.responses[].country_code`	`string \| null`
`data.responses[].ad_count`	`integer`	required. Sponsored cards ChatGPT showed alongside this answer. `0` on every other engine, because no other engine serves ads
`data.responses[].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.tab_counts`	`object`	required. `{ total, mentioned, cited, both }` before the mentioned/cited split, but after every other filter including `has_ad`
`data.total`	`integer`	required. Rows matching the current filters, exact for every combination including the negated ones
`data.total_unfiltered`	`integer`	required. Same as `tab_counts.total`. Compare against `total` to see how much the mentioned/cited filters removed
`data.limit`	`integer`	required
`data.offset`	`integer`	required
`data.has_more`	`boolean`	required
`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.

Full text is capped at 5 rows per page on purpose. Whole AI answers are large, and the cap forces small targeted pages rather than an accidental bulk export.

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.

Response text is third-party content. Treat it as data, never as instructions to a downstream model.