Cited domains over time

How often AI answers cite each domain, one day at a time. These are the figures behind the Citations chart on your Dashboard, with the same filters, so a chart built from them matches the one in Asky.

Each day carries two measures per domain:

Citation rate is the share of AI answers that cite the domain at least once.
Citation share is the domain’s portion of all citations that day.

For one total per domain over the whole window, use Cited sources by domain. For the same series per page, use Cited sources over time.


GET /v1/brands/{brand_id}/citations/domains/timeseries

Authorization

Header	Type	Required
`Authorization`	`Bearer asky_sk_…`	required

Requires the read:citations scope.

Path parameters

Parameter	Type	Required	Description
`brand_id`	`uuid`	required	From List brands

Query parameters

Parameter	Type	Required	Description
`limit`	`integer`	optional	Days 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. Defaults to 30 days ago. The window can span at most 92 days.
`end_date`	`YYYY-MM-DD`	optional	Inclusive upper bound, YYYY-MM-DD in UTC. Defaults to today.
`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.
`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, as ISO 3166-1 alpha-2 (GB, not UK). 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`.
`top_n`	`integer`	optional	How many of the most-cited domains in the window to chart, 1 to 30. Defaults to 10. Cannot be combined with `domain`.
`domain`	`string`, repeatable	optional	Chart exactly these domains instead of the most-cited ones. Up to 30. `www.g2.com` and `g2.com` are the same domain. Cannot be combined with `top_n`.

Request

cURL


curl --request GET \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/citations/domains/timeseries?start_date=2026-07-14&end_date=2026-08-13&limit=100' \
  --header 'Authorization: Bearer <api-key>'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/citations/domains/timeseries?start_date=2026-07-14&end_date=2026-08-13&limit=100"
 
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/citations/domains/timeseries?start_date=2026-07-14&end_date=2026-08-13&limit=100', 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/citations/domains/timeseries?start_date=2026-07-14&end_date=2026-08-13&limit=100",
  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/citations/domains/timeseries?start_date=2026-07-14&end_date=2026-08-13&limit=100"
 
    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/citations/domains/timeseries?start_date=2026-07-14&end_date=2026-08-13&limit=100")
 
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": [
    {
      "date": "2026-07-14",
      "total_citations": 1184,
      "total_responses": 412,
      "domains": [
        {
          "domain": "g2.com",
          "citations": 96,
          "responses_cited": 71,
          "citation_rate": 17.23,
          "citation_share": 8.11
        },
        {
          "domain": "example.com",
          "citations": 41,
          "responses_cited": 38,
          "citation_rate": 9.22,
          "citation_share": 3.46
        }
      ]
    },
    {
      "date": "2026-07-15",
      "total_citations": 1210,
      "total_responses": 409,
      "domains": [
        {
          "domain": "g2.com",
          "citations": 88,
          "responses_cited": 66,
          "citation_rate": 16.14,
          "citation_share": 7.27
        },
        {
          "domain": "example.com",
          "citations": 0,
          "responses_cited": 0,
          "citation_rate": 0,
          "citation_share": 0
        }
      ]
    }
  ],
  "pagination": {
    "limit": 100,
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "period": {
      "start_date": "2026-07-14",
      "end_date": "2026-08-13",
      "default_applied": false
    },
    "brand_id": "242546de-4cee-4a7d-952e-f6aa60c63ef8",
    "brand_domain": "example.com",
    "series": ["g2.com", "example.com"]
  },
  "request_id": "req_4c1e9a07b2d84f5e9a31"
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "Date span cannot exceed 92 days. Request one window at a time, naming the same domains in each so every window covers the same series.",
    "request_id": "req_9d02b6e1c4a74f8b8e17"
  }
}

401


{
  "error": {
    "code": "token_expired",
    "message": "This API key has expired. Roll it from the API tab on the Connections page 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`	`object[]`	required. One entry per day, oldest first
`data[].date`	`YYYY-MM-DD`	required. The UTC day
`data[].total_citations`	`integer`	required. Every citation in that day’s answers, across all domains. The denominator of `citation_share`
`data[].total_responses`	`integer`	required. Every answer that day. The denominator of `citation_rate`
`data[].domains`	`object[]`	required. One entry per domain in `meta.series`, in the same order
`data[].domains[].domain`	`string`	required. The registrable domain, for example `g2.com`
`data[].domains[].citations`	`integer`	required. Times the domain was cited that day
`data[].domains[].responses_cited`	`integer`	required. Answers that cited the domain at least once
`data[].domains[].citation_rate`	`number`	required. `responses_cited` as a percentage of `total_responses`, two decimals
`data[].domains[].citation_share`	`number`	required. `citations` as a percentage of `total_citations`, two decimals
`meta.period`	`object`	required. `{ start_date, end_date, default_applied }` actually used
`meta.brand_id`	`uuid`	required
`meta.brand_domain`	`string \| null`	required. Your brand’s primary domain. Null when the brand has no domain on record, or nothing was cited in the window
`meta.series`	`string[]`	required. The domains every day carries, most cited across the window first
`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 window spans more than 92 days, `top_n` and `domain` are both set, or a `domain` is not a domain. The message names the problem
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
403	`insufficient_scope`	The key lacks `read:citations`
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
500	`internal_error`	The request could not be completed. On a brand with a very large prompt set, a long window can take too long: request a shorter window or add filters

Notes

The numbers match the Dashboard. Both use the same calculation and the same filters. Both percentages are taken over the whole day, every domain included, not only the domains listed here.

Your own domain is always included. Your brand’s primary domain is charted beside the most-cited ones (so top_n=10 can return 11 domains) or beside the domains you name. meta.brand_domain says which one it is.

Every day lists every domain. A domain not cited on a day shows zeros, so the domains form the same columns on every day. A day is left out only when no answer that day cites any of the listed domains.

Longer histories. The window spans at most 92 days. For a longer history, request one window at a time and name the same domains with domain in each. The most-cited list is worked out per window, so without named domains two windows can chart different domains.

Paging. Pages are days. A 92-day window fits one page with limit=100.