Skip to main content
Every timeseries request answers two questions: at what resolution, and over what window. The granularity is a path segment; the time window is a query parameter.

​
Granularity

Granularity is part of the URL path, not a query parameter:
Each model supports only a subset of these. 1d is the most widely available; some models add 1w or 1h, and only a handful go down to 5m. Requesting a granularity a model does not offer returns 404.
Read the supported set from the model’s intervals array in the timeseries catalog, or from the granularity path parameter’s enum on the endpoint’s reference page.
1n is a legacy token for a calendar month, carried over from earlier API versions and still used by a few monthly models (fundraising, for example). Where it appears in a model’s intervals, it is the correct value to put in the path.

​
Time windows

There are two mutually exclusive ways to select a window: timeframe, or start/end.
Combining them returns 400 with cannot combine timeframe with start/end. Pick one style per request.
If you supply neither, the window is unbounded below and ends at the current time: you get everything the API retains for that series. A window may span at most 9000 points of the requested granularity, so omitting it works at 1d and coarser but returns 400 at fine granularities such as 1h, where the full history is wider than that. bounds=true is exempt from the cap.

​
timeframe

A single expressive token. Windows anchored to “now” end at the current time. Relative windows accept the units m (minutes), h (hours), d (days), and w (weeks), written as a count followed by the unit. Tokens are case-insensitive: YTD and 30D work.
There is no year or month unit. 1y and 1M return 400 with unrecognized timeframe "1y". For the last year use 365d or 52w; for the calendar year to date use ytd; for a whole past year or month use the calendar forms 2025 or 2025-06; for anything else use start/end.
In full, timeframe accepts exactly these forms:
A bare number is read as a calendar year when it falls between 1970 and 3000, and as a unix timestamp otherwise. If you mean a specific instant inside that range, use RFC3339 or start.

​
start and end

For explicit windows. Each accepts RFC3339, unix seconds, or YYYY-MM-DD. Both are optional: an omitted start leaves the window unbounded below, and an omitted end defaults to now.
A start later than end returns 400.
Windows are half-open: [start, end). A calendar expansion such as timeframe=2026-07-13 runs from that midnight up to, but not including, the next, so adjacent windows never double-count a bucket.

​
bounds

Set bounds=true to return only the first and last point of the resolved window instead of every point in it. This is the efficient way to compute a change over a period without transferring the whole series.

​
Timestamps in the response

Every point begins with a unix timestamp in seconds, in UTC. The values that follow are the metrics in point_schema order. See Responses.

​
Choosing a granularity

Match the window

A year of 5m data is a very large response. Use 1d for long windows and reserve fine granularities for short ones.

Check what exists

Read intervals from the catalog before hardcoding a granularity, because the supported set differs per model.
For long windows at fine granularity, request acceptFormat=csv or acceptFormat=jsonl to receive the data as a downloadable file rather than a single JSON document. See Filtering & pagination.