Metrics API

Record and query numeric measurements and counters.

Metric types

Metrics are numeric data points distinct from events, recorded either as measurements or counters. The type is fixed per metric name within a project:

Measurement: an observed value at a point in time, such as a request taking 84 milliseconds. The default aggregation is avg.
Counter: a quantity that changes through increments and decrements. Over any range, its sum is the net change, not a running total.

Submit a metric

http

POST /v1/projects/:projectId/metrics

Records a measurement or a counter change and returns 201 Created. A measurement maps to an $measure internal event; increments and decrements map to $increment and $decrement.

json

{
  "type": "measurement",
  "name": "api.latency",
  "value": 84,
  "unit": "ms",
  "tags": { "route": "/v1/users" }
}

json

{
  "type": "increment",
  "name": "jobs.processed",
  "value": 1
}

json

{
  "type": "decrement",
  "name": "queue.depth",
  "value": 1
}

Request fields:

Field	Type	Description
`type`	string	One of `measurement`, `increment`, or `decrement`.
`name`	string	Metric name. Required. Must not start with `$`.
`value`	number	Observed value (measurement) or change amount (counter). Counter changes must be non-negative.
`unit`	string	Optional unit such as `ms` or `bytes`.
`timestamp`	string	ISO 8601 timestamp. Defaults to the current time.
`tags`	object	Optional key/value dimensions.

Response:

json

{
  "data": { "accepted": 1 }
}

Submit a batch

http

POST /v1/projects/:projectId/metrics/batch

Records up to 500 metrics in one request. Each element uses the samemeasurement, increment, or decrement shape as a single submission.

json

{
  "metrics": [
    { "type": "measurement", "name": "api.latency", "value": 84, "unit": "ms" },
    { "type": "increment", "name": "jobs.processed", "value": 1 }
  ]
}

Query metric values

http

POST /v1/projects/:projectId/metrics/query

Runs an aggregated query over a time range. The aggregation defaults to avg for measurements and is one of avg, min, max, sum, count, p50, p90, p95, or p99. For a counter, the result is the net change over the range. A type of counter with an operation of increment or decrement narrows the query to one side of a counter.

json

{
  "name": "api.latency",
  "aggregation": "avg",
  "time": {
    "start": "2026-08-20T00:00:00Z",
    "end": "2026-08-21T00:00:00Z"
  }
}

Response:

json

{
  "data": {
    "name": "api.latency",
    "type": "measurement",
    "unit": "ms",
    "aggregation": "avg",
    "value": 87.4,
    "count": 120
  }
}

Metric timeseries

http

POST /v1/projects/:projectId/metrics/timeseries

Returns metric values bucketed over time. The interval is one of 1m, 5m, 15m, 30m, 1h, 6h, 12h, 1d, or 1w. For a counter, each bucket contains the net change during that bucket.

json

{
  "name": "api.latency",
  "interval": "1h",
  "aggregation": "avg",
  "time": {
    "start": "2026-08-20T00:00:00Z",
    "end": "2026-08-21T00:00:00Z"
  }
}

Response:

json

{
  "data": {
    "name": "api.latency",
    "type": "measurement",
    "unit": "ms",
    "interval": "1h",
    "buckets": [
      { "timestamp": "2026-08-20T00:00:00Z", "value": 82.1, "count": 15 },
      { "timestamp": "2026-08-20T01:00:00Z", "value": 91.3, "count": 21 }
    ]
  }
}

Buckets are aligned to UTC boundaries, and buckets with no observations are not emitted, so the series can have gaps.

Raw data points

http

POST /v1/projects/:projectId/metrics/points

Returns the raw submitted points for a metric within a time range, unaggregated, useful for drawing scatter plots or inspecting exact values.

json

{
  "name": "api.latency",
  "time": {
    "start": "2026-08-20T00:00:00Z",
    "end": "2026-08-21T00:00:00Z"
  }
}

Current value

http

POST /v1/projects/:projectId/metrics/current

Returns the latest state of a metric without a time range. For a counter this is the all-time cumulative value; for a measurement it is the most recent observation along with its timestamp.

json

{
  "name": "jobs.processed"
}

Response:

json

{
  "data": {
    "name": "jobs.processed",
    "type": "counter",
    "value": 4820,
    "lastTimestamp": "2026-08-24T10:32:01.000Z"
  }
}

List metrics

http

GET /v1/projects/:projectId/metrics

Lists every metric name recorded for the project with its fixed type.

Response:

json

{
  "data": [
    { "name": "api.latency", "type": "measurement" },
    { "name": "jobs.processed", "type": "counter" }
  ]
}