Cited sources over time

How often AI answers cite each page, one day at a time. These are the figures behind the pages tab of 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 page:

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

For counts and one total per page over the whole window, use List cited sources. For the same series per domain, use Cited domains over time.


GET /v1/brands/{brand_id}/citations/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 pages in the window to chart, 1 to 30. Defaults to 10. Cannot be combined with `url`.
`url`	`string`, repeatable	optional	Chart exactly these pages instead of the most-cited ones. Up to 30. Pass each URL exactly as List cited sources returns it, URL-encoded. Cannot be combined with `top_n`.

Request

cURL


curl --request GET \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/citations/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/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/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/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/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/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",
      "urls": [
        {
          "url": "https://www.g2.com/categories/ai-search-monitoring",
          "citation_rate": 6.31,
          "citation_share": 2.2
        },
        {
          "url": "https://example.com/pricing",
          "citation_rate": 3.4,
          "citation_share": 1.18
        }
      ]
    },
    {
      "date": "2026-07-15",
      "urls": [
        {
          "url": "https://www.g2.com/categories/ai-search-monitoring",
          "citation_rate": 5.87,
          "citation_share": 1.98
        },
        {
          "url": "https://example.com/pricing",
          "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",
    "series": [
      "https://www.g2.com/categories/ai-search-monitoring",
      "https://example.com/pricing"
    ]
  },
  "request_id": "req_6e3b1f90a7c24d18b5e2"
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "Choose the series by top_n or by naming URLs, not both.",
    "request_id": "req_2a7f0c93e1b54d6aa0c8"
  }
}

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[].urls`	`object[]`	required. One entry per page in `meta.series`, in the same order
`data[].urls[].url`	`string`	required. The cited page, as List cited sources returns it
`data[].urls[].citation_rate`	`number`	required. Percentage of that day’s answers citing the page, two decimals
`data[].urls[].citation_share`	`number`	required. The page’s percentage of all citations that day, two decimals
`meta.period`	`object`	required. `{ start_date, end_date, default_applied }` actually used
`meta.brand_id`	`uuid`	required
`meta.series`	`string[]`	required. The pages every day carries, highest average daily share 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, or `top_n` and `url` are both set. 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 page included, not only the pages listed here.

Rates and shares only. Pages carry percentages, not counts. For citation counts per page, use List cited sources over the same window. For counts per day, use Cited domains over time.

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

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

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