Querying metrics

Read metric data with the Public API (V2). Fetch a timeseries for graphs, an aggregated list for tables, or discover which metrics and tags a site has. All endpoints authenticate with your personal API token and are scoped to a single site_id.

Migrate from GraphQL metrics

Reading metrics through the GraphQL API is deprecated. If your integration reads metric data through GraphQL, use this comparison to move it to the REST API (V2) timeseries endpoint.

What you need	GraphQL metrics	REST API (V2)
Endpoint	POST https://appsignal.com/graphql?token=YOUR-TOKEN	POST https://appsignal.com/api/v2/metrics/timeseries
Authentication	Personal API token in a URL query parameter	Personal API token in a bearer header or a URL query parameter. See authentication.
App identifier	Pass the app ID to app(id: $appId)	Pass the app ID as site_id in the request body.
Tag filters	An array of key-value pairs, such as [{ "key": "namespace", "value": "web" }]	An object, such as { "namespace": "web" }
Fields	A fields array on each metric query	One uppercase field on each select entry, such as "MEAN" or "P90". Use uppercase values for aggregation too.
Matching data	Query app.metrics.keys and app.metrics.timeseries separately.	Make one timeseries request. The returned series array identifies the tag and field combinations that returned data. Processing limits can make this list incomplete.
Paging	metrics.list and metrics.keys accept limit and offset.	No offset. Results are capped by the processing limits.
Missing data points	The metrics query does not configure how to fill missing points.	Use the optional fill field. It accepts "ZERO", "PREVIOUS", or "NONE" and defaults to "ZERO". The legacy draw_null_as_zero field is also supported.

Query a timeseries

This endpoint returns one or more series of data points over a time range. Use it to draw graphs.

Endpoint

POST /api/v2/metrics/timeseries

Request body

Field	Type	Required	Description
site_id	string	Yes	Site to query.
from	string (ISO 8601)	Yes	Time range start (inclusive).
to	string (ISO 8601)	Yes	Time range end (inclusive).
select	TimeseriesSelector[]	Yes	Which metrics, fields, and tags to fetch.
resolution	Resolution	No	Interval between data points. Chosen automatically when omitted.
limit	number	No	Requested maximum number of series to return. This field is currently not applied to timeseries queries.

Each select entry requests one metric field. Provide a metric name, a tags object, and a field (see fields). Tag values may use * as a wildcard. You can also provide an aggregation (see aggregations) and a fill value.

The fill values are ZERO (the default), PREVIOUS, and NONE. Existing integrations can also use the optional draw_null_as_zero field. If you send both fields, fill takes precedence.

Use uppercase values for field and aggregation. The timeseries endpoint does not support group_by.

body.json

{
  "site_id": "YOUR-SITE-ID",
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T01:00:00Z",
  "resolution": "MINUTELY",
  "select": [
    {
      "name": "trace_duration",
      "tags": { "namespace": "web" },
      "field": "MEAN",
      "aggregation": "AVERAGE",
      "draw_null_as_zero": false
    }
  ]
}

Response

Returns a Timeseries with the queried resolution, from, to, and a series array. Each series has an id, the metric name, its tags, the field it represents, min and max across the range, and a data array of points. Each point has a timestamp and a numeric value.

Unlike the GraphQL metrics API, this endpoint does not require a separate metric keys request. Use the series array to see which tag and field combinations returned data. If a query may reach the processing limits, do not use series.length as the total number of matching metric keys.

Query a list

This endpoint returns aggregated metric values grouped into rows. Use it to build tables.

Endpoint

POST /api/v2/metrics/list

Request body

Field	Type	Required	Description
site_id	string	Yes	Site to query.
from	string (ISO 8601)	Yes	Time range start (inclusive).
to	string (ISO 8601)	Yes	Time range end (inclusive).
select	ListSelector[]	Yes	Which metrics, fields, and tags to fetch.
group_by	GroupBy[]	Yes	How to group rows.
resolution	Resolution	No	Interval used for aggregation.
limit	number	No	Maximum row count to return.

A ListSelector is like a timeseries selector, with an extra id that names the selector’s value in each row’s data object. group_by entries are Name (group by metric name) or Tag (group by a tag value).

Use uppercase values for field and aggregation. The case-sensitive group_by values are Name and Tag. If a selector uses * for a tag in tags, add the same tag to group_by as {"Tag": "tag_name"} or the request fails.

body.json

{
  "site_id": "YOUR-SITE-ID",
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T01:00:00Z",
  "resolution": "HOURLY",
  "select": [
    {
      "id": "mean",
      "name": "trace_duration",
      "tags": { "namespace": "*" },
      "field": "MEAN",
      "aggregation": "AVERAGE"
    }
  ],
  "group_by": [{ "Tag": "namespace" }],
  "limit": 50
}

Response

Returns a List with the queried resolution, from, to, and a rows array. Each row has an id, a group object of the tag values that define it, and a data object of aggregated values keyed by selector id (for example, { "mean": 42.5 }).

List metric names

Return every metric name available for a site.

Endpoint

GET /api/v2/metrics/names/{site_id}

Returns an array of strings.

Get a metric’s type and tags

Return a metric’s type and the tag combinations it can be queried with.

Endpoint

GET /api/v2/metrics/type_and_tags/{site_id}/{metric_name}

Returns a metric_type (GAUGE, COUNTER, or MEASUREMENT) and available_tags, an array where each entry is one valid combination of tag keys.

High-cardinality metric queries

A metric query has high cardinality when it matches more series than the endpoint can process. AppSignal stores each unique tag combination as a separate metric key. For example, every combination of queue and worker values creates a separate metric key.

The limits in this section apply to custom metrics and transaction_duration. They also apply to incident_error_count when a query uses a wildcard for incident_digest or revision. They do not apply to other metrics in the current V2 implementation.

Each metric key and field combination counts as one series. For example, requesting MEAN and COUNT for one metric key counts as two series.

For affected metrics, AppSignal limits how many series it processes before fetching their data:

• /api/v2/metrics/timeseries processes up to 100 series.
• /api/v2/metrics/list processes up to 1,000 series.

These limits protect the metrics database from queries that would take too long to complete. They apply to the whole response, not separately to each select entry. The limit field cannot raise them. Dashboard charts load their data from /api/v2/metrics/timeseries, so the 100-series limit applies to charts too.

If a query matches more series than the endpoint can process, AppSignal returns only part of the data. The response does not indicate that it is incomplete, so aggregated totals may be too low. Repeating the same query returns the same subset, but the result is still incomplete.

The Limits page shows which custom metrics report the most unique tag combinations per minute. When tag values change over time, a query over a longer range can match more series than the page shows.

Custom metrics work best with tags that have a small, fixed set of values, such as region, plan, or queue. If an existing metric has high-cardinality tags, exact tag filters can reduce the number of matching series. However, the response cannot confirm that it contains every series. See Metric tags for guidance on choosing tag values.

Reference

Fields

The field selects which measurement to retrieve from a metric:

Value	Description
GAUGE	The metric’s value at a single moment in time, such as current CPU or memory usage.
COUNTER	From COUNTER metrics, the cumulative value, which only increases over time, such as the number of requests served.
MEAN	The average of the values recorded in the time bucket, such as average response time.
COUNT	From MEASUREMENT metrics, how many values were recorded during the time bucket.
MIN	The lowest value recorded in the time bucket.
MAX	The highest value recorded in the time bucket.
P99, P95, P90, P80, P75, P70, P60, P50, P40, P30, P20, P10	Percentile values.

For more type references, read the AppSignal V2 API Documentation.

Aggregations

The aggregation combines multiple values within a time bucket: SUM, AVERAGE, MIN, MAX, FIRST, or LAST.

Resolutions

resolution accepts MINUTELY, FIVE_MINUTELY, TEN_MINUTELY, FIFTEEN_MINUTELY, HOURLY, or DAILY.