Skip to main content
POST
Aggregate a metric over time

Authorizations

Authorization
string
header
required

A project token (apsio_pt_v0...), which reads exactly one project, or an OAuth access token issued for the API, which reads what its user can. Access tokens issued for Apsio's MCP server are accepted only from the MCP server itself.

Path Parameters

projectId
string
required
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"0192f3a4-0000-7000-8000-00000000a101"

Body

application/json
metric
string
required

The metric's name, as the catalog lists it.

Pattern: ^[A-Za-z0-9_.:/-]{1,255}$
Example:

"apsio.metrickit.time_to_first_draw"

kind
enum<string>
required

sum and gauge points are in metric_values, histograms in metric_histograms.

Available options:
sum,
gauge,
histogram
aggregation
enum<string>
required

Per bucket: count (points, or a histogram's observations), rate (a sum's total or a histogram's observations per minute), sum, avg, min, max, or a percentile. A gauge takes count, avg, min, max and percentiles.

Available options:
count,
rate,
sum,
avg,
min,
max,
p50,
p90,
p95,
p99
from
string<date-time>

Start, inclusive (RFC 3339). Defaults to 24 hours before to.

to
string<date-time>

End, exclusive (RFC 3339). Defaults to now.

app_id
string

Only this app of the project.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
filters
object[]
Maximum array length: 20
group_by
string

One field (service.version, os.name, os.version, device.model.identifier, country, ...), any point attribute by its key, or a resource attribute as resource.: the 10 groups with the most points, and the rest as one series.

Pattern: ^[A-Za-z0-9_.:/-]{1,128}$

Response

The series.

from
string
required

RFC 3339 time in UTC with up to nanosecond precision.

Example:

"2026-10-04T10:15:00.431000000Z"

to
string
required

RFC 3339 time in UTC with up to nanosecond precision.

Example:

"2026-10-04T10:15:00.431000000Z"

bucket_seconds
integer
required
retention_days
integer
required

Days of detail the project's plan keeps (D94); nothing older is read.

metric
string
required
kind
enum<string>
required
Available options:
sum,
gauge,
histogram
aggregation
enum<string>
required
Available options:
count,
rate,
sum,
avg,
min,
max,
p50,
p90,
p95,
p99
unit
string
required

The metric's unit (UCUM, as the app reports it). Written by the app: untrusted data.

group_by
string | null
required
series
object[]
required

Every bucket of the range in each series, the largest group first.

sql
string
required

The query with its values, for reading. Not run as written.