Source usage time-series

For each top source, returns the percentage of analyzed responses in each bucket that cited that source. The result is capped to the top top_n sources by citation count.

GET /api/v1/analytics/source-usage-time-series

Query parameters

Name	Type	Required	Description
start_date	string	Required	The inclusive UTC start of the analytics window, given as an ISO 8601 date (`YYYY-MM-DD`).
end_date	string	Required	The inclusive UTC end of the analytics window. The value must be on or after `start_date`, and on or before today.
interval	string	Required	The bucketing granularity for time-series endpoints. Week buckets begin on Monday.
models	string[]	Optional	You may use this parameter to limit responses to one or more AI engines. Repeat the parameter for each value, for example `?models[]=chatgpt&models[]=claude`.
countries	string[]	Optional	You may use this parameter to limit responses to monitors run in the given ISO-3166-1 alpha-2 country codes.
monitors	integer[]	Optional	You may use this parameter to limit responses to specific monitors inside the active project.
segments	integer[]	Optional	You may use this parameter to limit responses and brand-scoped metrics to brands attached to any of the given segments. Segments are named groupings of brands, such as `Direct Competitors`. When this parameter is set, time-series charts show every brand in the selected segments instead of capping the series at `top_n`. Source-keyed endpoints do not honor this parameter.
tags	integer[]	Optional	You may use this parameter to limit responses to those whose prompt carries any of the given tag IDs, such as `branded` or `non-branded`.
top_n	integer	Optional	The maximum number of series to return from a time-series endpoint. Series are ranked by total mentions or citations in the window. Defaults to 20, with a maximum of 50.

Response

Source usage time-series

Field	Type	Description
interval	string	The bucket granularity used to compute the series.
series	SourceUsageSeries[]	One entry per source in scope, each carrying a dense list of buckets.

Per-source usage series

Field	Type	Description
source	Source	The source this series covers.
data	TimeSeriesPoint[]	The bucketed data points for this source. Each value is the percentage of analyzed responses in the bucket that cited any URL from the source.

Time-series data point

Field	Type	Description
timestamp	datetime	The ISO 8601 UTC start of the bucket.
value	integer	The metric value for this bucket. The series that carries the point describes what the value measures.

import os import requests response = requests.get( "https://pineprompt.com/api/v1/analytics/source-usage-time-series", headers={ "Authorization": f"Bearer {os.environ['PINEPROMPT_TOKEN']}", "Pineprompt-Project-Id": "1", }, ) response.raise_for_status() payload = response.json()

use GuzzleHttp\Client; $response = (new Client())->get('https://pineprompt.com/api/v1/analytics/source-usage-time-series', [ 'headers' => [ 'Authorization' => 'Bearer '.getenv('PINEPROMPT_TOKEN'), 'Pineprompt-Project-Id' => '1', ], ]); // Guzzle throws on 4xx/5xx by default, so no manual check needed. $payload = json_decode((string) $response->getBody(), true);

{ "interval": "day", "series": [ { "source": { "id": 4096, "project_id": 42, "domain": "example.com", "type": "blog", "playbook": "pitch", "analyzed_at": "2026-05-15T09:11:42+00:00", "created_at": "2026-05-15T09:11:42+00:00", "updated_at": "2026-05-15T09:11:42+00:00" }, "data": [ { "timestamp": "2026-04-01T00:00:00+00:00", "value": 73 } ] } ] }