> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Querying metrics

Read metric data with the [Public API (V2)](/api/v2/overview). 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`.

## Query a timeseries

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

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/metrics/timeseries
  ```
</CodeGroup>

### 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       | Maximum series count to return.                                  |

Each `select` entry takes a metric `name`, a `tags` object to filter on (values
may use `*` as a wildcard), a `field` (see [fields](#fields)), an optional
`aggregation` (see [aggregations](#aggregations)), and `draw_null_as_zero` (when `true`, missing points are filled with `0`).

<CodeGroup>
  ```json body.json theme={null}
  {
    "site_id": "YOUR-SITE-ID",
    "from": "2026-06-22T00:00:00Z",
    "to": "2026-06-22T01:00:00Z",
    "resolution": "MINUTELY",
    "select": [
      {
        "name": "transaction_duration",
        "tags": { "namespace": "web" },
        "field": "mean",
        "aggregation": "avg",
        "draw_null_as_zero": false
      }
    ],
    "limit": null
  }
  ```
</CodeGroup>

### 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`.

## Query a list

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

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/metrics/list
  ```
</CodeGroup>

### 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).

<CodeGroup>
  ```json body.json theme={null}
  {
    "site_id": "YOUR-SITE-ID",
    "from": "2026-06-22T00:00:00Z",
    "to": "2026-06-22T01:00:00Z",
    "resolution": "HOURLY",
    "select": [
      {
        "id": "mean",
        "name": "transaction_duration",
        "tags": { "namespace": "*" },
        "field": "mean",
        "aggregation": "avg"
      }
    ],
    "group_by": ["Name"],
    "limit": 50
  }
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```shell Endpoint theme={null}
  GET /api/v2/metrics/names/{site_id}
  ```
</CodeGroup>

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.

<CodeGroup>
  ```shell Endpoint theme={null}
  GET /api/v2/metrics/type_and_tags/{site_id}/{metric_name}
  ```
</CodeGroup>

Returns a `metric_type` (`gauge`, `counter`, or `measurement`) and
`available_tags`, an array where each entry is one valid combination of tag keys.

## 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.                                                                       |
| `p_90`, `p_95` | Percentile values.                                                                                                   |

For more type references, read the [AppSignal V2 API Documentation](https://appsignal.com/api/v2/docs).

### Aggregations

The `aggregation` combines multiple values within a time bucket: `sum`, `avg`,
`min`, `max`, `first`, or `last`.

### Resolutions

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