Get an analytics series
GET/v1/analytics/seriespreview
Get counters per step over a range, one series for the key of a dimension. A read that is too large is refused with 400 validation_failed, never cut short: one that spans more than 400 steps, or covers too much detail. Narrow the range or use a coarser step.
Query parameters
dimensionstring RequiredWhat a series is keyed by: app (one series for the whole app), event_type, destination, or latency (a latency histogram of one destination or of the whole app).
Allowed values: "app", "event_type", "destination", "latency"
stepstring RequiredThe width of one point: hour, day, week (starting Monday), month or year, in UTC.
Allowed values: "hour", "day", "week", "month", "year"
fromstring (date-time) RequiredThe inclusive start of the range, aligned to the step in UTC.
tostring (date-time) RequiredThe exclusive end of the range, aligned to the step in UTC.
keystring OptionalOne destination ID or event type. Required for every dimension except app, which is refused a key. For the latency dimension ‘’ is the app-wide row.
metricstring OptionalRequired for the latency dimension, and refused for the others. attempt is one HTTP request to a destination. queue spans event accepted to first attempt started, delivery spans event accepted to first success, and terminal spans event accepted to success or the last failed attempt.
Allowed values: "attempt", "queue", "delivery", "terminal"
Returns
The query result.200
dataobject RequiredOne series per key, each with one point per step.
dimensionstring RequiredWhat a series is keyed by: app (one series for the whole app), event_type, destination, or latency (a latency histogram of one destination or of the whole app).
Allowed values: "app", "event_type", "destination", "latency"
stepstring RequiredThe width of one point: hour, day, week (starting Monday), month or year, in UTC.
Allowed values: "hour", "day", "week", "month", "year"
fromstring (date-time) RequiredThe inclusive start of the range.
tostring (date-time) RequiredThe exclusive end of the range.
seriesobject[] RequiredOne series per key, sorted by key. The app dimension has one series with a null key.
Show child attributesHide child attributes
keystring | null RequiredThe destination ID or event type the row belongs to. Null for the app dimension. ‘’ for the app-wide latency row, and ‘pp/other’ for the event types past the monthly cap, which are counted together. Event types starting with ‘pp/’ are reserved.
pointsobject[] RequiredOne point per step from
fromtoto, oldest first, with empty steps filled with 0.Show child attributesHide child attributes
atstring (date-time) RequiredThe start of the step.
valuesobject RequiredCounters summed into the step, by name. App and destination values carry attempts, delivered, failed and retried, and destination values also carry status classes and latency extremes in milliseconds. unhealthy counts attempts that say the endpoint is failing (a network error, a 3xx, a 5xx, a 4xx other than 400, 413, 422 and 429), and ignored counts attempts that say nothing about it: a payload rejection (400, 413, 422), a 429, and a failed or delivered attempt numbered 3 or more of one delivery. Latency values carry p50, p95 and p99 in milliseconds and the sample count. A counter with nothing recorded is 0.
Example
curl -X GET "https://api.payloadpuffin.com/v1/analytics/series?dimension=app&step=hour&from=2026-10-21T00%3A00%3A00.000Z&to=2026-10-22T00%3A00%3A00.000Z" \
-H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY"{
"data": {
"dimension": "app",
"step": "hour",
"from": "from",
"to": "to",
"series": [
{
"key": "key",
"points": [
{
"at": "at",
"values": {}
}
]
}
]
}
}Errors
Errors use application/problem+json. The code member is stable; branch on it rather than on title or detail.
4XXapplication/problem+jsonThe request was rejected.