Skip to main content
Returns an array of DataPoint objects for the specified indicator. Supports date range filtering, sort order, pagination, and aggregation by time window.

​
Path parameters

​
indicator_id
string
required
The indicator’s unique identifier. Must be a valid MongoDB ObjectId (24-character hex string).

​
Query parameters

​
skip
integer
default:"0"
Number of data points to skip. Minimum: 0. Use with limit for pagination.
​
limit
integer
default:"100"
Maximum number of data points to return. Minimum: 1, maximum: 10000.
​
sort
string
default:"asc"
Sort order for the x-axis values. Accepted values: asc, desc.
​
start_date
string
Filter to data points at or after this datetime. ISO 8601 format (e.g., 2024-01-01T00:00:00Z).
​
end_date
string
Filter to data points at or before this datetime. ISO 8601 format (e.g., 2024-12-31T23:59:59Z).
​
granularity
string
default:"0"
Aggregation time window. Use "0" to return raw data with no aggregation.
ValueWindow
0No aggregation (raw points)
1s1 second
5m5 minutes
1h1 hour
1d1 day
1w1 week
1M1 month
1y1 year
Any positive integer combined with a unit suffix is valid (e.g., 15m, 6h, 3M).
​
aggregator
string
default:"last"
Aggregation method applied within each granularity window. Ignored when granularity is "0".
ValueDescription
lastLast value in the window
firstFirst value in the window
sumSum of all values
avgArithmetic mean
medianMedian value
maxMaximum value
minMinimum value
countNumber of data points in the window
p{N}Nth percentile, where N is 0–100 (e.g., p50, p95, p99)
Percentile aggregation uses MongoDB’s approximate percentile algorithm. For exact median, use median instead of p50.

​
Response

Returns an array of DataPoint objects.
​
x
string | number
required
The x-axis value. For time-series indicators this is an ISO 8601 datetime string. For numeric indicators this is a float.
​
y
number
required
The measured value at point x.

​
Response headers

HeaderDescription
X-Total-CountNumber of data points returned in this response.

​
Error responses

StatusDescription
400 Bad Requestindicator_id is not a valid ObjectId, or aggregator value is not recognized.

​
Examples

curl -X GET \
  "https://api.example.com/indicators/64b1f2c3d4e5f6a7b8c9d0e1/data?limit=50&sort=asc" \
  -H "Accept: application/json"

import httpx

client = httpx.AsyncClient(base_url="https://api.example.com")
response = await client.get(
    "/indicators/64b1f2c3d4e5f6a7b8c9d0e1/data",
    params={"limit": 50, "sort": "asc"},
)
response.raise_for_status()
points = response.json()
print(response.headers["X-Total-Count"])  # e.g. "50"

​
Example response

200
[
  { "x": "2024-01-01T00:00:00", "y": 1423.5 },
  { "x": "2024-02-01T00:00:00", "y": 1587.2 },
  { "x": "2024-03-01T00:00:00", "y": 1349.8 }
]
400 Invalid aggregator
{
  "detail": "Invalid aggregator: p101. Valid options: ['last', 'first', 'sum', 'avg', 'median', 'max', 'min', 'count'] or percentiles (p0-p100)"
}
400 Invalid indicator ID
{
  "detail": "Invalid indicator ID"
}
Results are served from a Redis cache when available. On repeated requests with the same parameters, responses are significantly faster. After a configurable number of cache misses, the full dataset for the given granularity and aggregator is pre-cached in the background.

Build docs developers (and LLMs) love

Get started for freeTalk to us