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

# Public API (V2)

The Public API (V2) is a REST API for reading raw application data: metrics,
traces, logs, Kubernetes metrics, and deploy statistics. It complements the
[GraphQL API](/api/graphql), which manages models such as apps, incidents,
dashboards, and alerts. As a rule of thumb, use the REST API to read data and
the GraphQL API to manage configuration.

<Tip>
  If you're building an AI agent or assistant, [AppSignal MCP](/mcp-server)
  exposes this data to agents directly — you may not need to call this API
  yourself.
</Tip>

## Base URL

All endpoints are served under `/api/v2` on the `appsignal.com` domain:

<CodeGroup>
  ```shell Base URL theme={null}
  https://appsignal.com/api/v2
  ```
</CodeGroup>

## Authentication

Requests are authenticated with your personal API token, passed either as a
bearer token or as a query parameter. You can find your token in the [personal
settings screen](https://appsignal.com/users/edit).

<CodeGroup>
  ```shell Authorization header theme={null}
  curl -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
    https://appsignal.com/api/v2/metrics/names/YOUR-SITE-ID
  ```

  ```shell Query parameter theme={null}
  curl "https://appsignal.com/api/v2/metrics/names/YOUR-SITE-ID?token=YOUR-PERSONAL-API-TOKEN"
  ```
</CodeGroup>

Your token grants access to the same sites and organizations you can see in
AppSignal. Most requests are scoped to a single `site_id`; tracing endpoints use
a `site_ids` array so they can search across multiple sites. The API checks that
your token has access to every requested site before returning data. To verify a
token itself, call `GET /api/v2/auth`.

Your `site_id` is the ID in your app's URL:
`https://appsignal.com/<organization>/sites/<SITE_ID>`. For log queries you also
need a log source ID — see [finding your site and source
IDs](/api/v2/logs#finding-your-site-and-source-ids).

## Verify a token

<CodeGroup>
  ```shell Endpoint theme={null}
  GET /api/v2/auth
  ```
</CodeGroup>

Returns a JSON object with a `message` confirming the authenticated user ID.

## Requests and responses

Most endpoints use `POST` with a JSON body and return JSON. Read-only lookups
(such as listing metric names) use `GET` with path parameters. Set
`Content-Type: application/json` on requests with a body.

Times are ISO 8601 strings. Most query bodies take a `from` and `to` time range
plus either a `site_id` or, for tracing endpoints, a `site_ids` array.

For a complete, auto-generated reference of every endpoint, request, and response
type, see the [REST API reference](https://appsignal.com/api/v2/docs).

## Error responses

Any endpoint can return these non-2xx responses:

| Status | Meaning                                | Body                                       |
| ------ | -------------------------------------- | ------------------------------------------ |
| `401`  | Missing or invalid token               | `{ "error": "Unauthorized" }`              |
| `404`  | Route or resource not found            | `{ "error": "Not found" }`                 |
| `422`  | Request parsed but cannot be processed | Error envelope (see the following section) |
| `500`  | Unhandled server-side failure          | `{ "error": "<message>" }`                 |

### 422 envelope

Every `422` response uses the same envelope, so you can handle them in one place:

<CodeGroup>
  ```json 422 response theme={null}
  {
    "error": "<stable_slug>",
    "message": "<human-readable message>",
    "details": {}
  }
  ```
</CodeGroup>

* `error`: a stable, machine-readable slug. Branch on this in your code.
* `message`: a human-readable message, safe to display.
* `details`: an optional object whose shape depends on `error`.

One slug you may encounter is `legacy_log_query_syntax`, returned when a logs
query uses the legacy `attributes.<name>_<type>` syntax. See [querying
logs](/api/v2/logs) for the current query language.

## Endpoints

### Metrics

| Method | Path                                                    | Description                                          |
| ------ | ------------------------------------------------------- | ---------------------------------------------------- |
| `POST` | `/api/v2/metrics/timeseries`                            | Query metric data as a timeseries                    |
| `POST` | `/api/v2/metrics/list`                                  | Query aggregated metric data as a list with grouping |
| `GET`  | `/api/v2/metrics/names/{site_id}`                       | List all metric names for a site                     |
| `GET`  | `/api/v2/metrics/type_and_tags/{site_id}/{metric_name}` | Get a metric's type and available tags               |

See the [metrics reference](/api/v2/metrics).

### Tracing

| Method | Path                                  | Description                                      |
| ------ | ------------------------------------- | ------------------------------------------------ |
| `POST` | `/api/v2/tracing/locator`             | Locate a trace across sites by trace ID          |
| `POST` | `/api/v2/tracing/trace`               | Get all spans for a trace                        |
| `POST` | `/api/v2/tracing/trace/performance`   | Get spans for a performance trace                |
| `POST` | `/api/v2/tracing/trace/error`         | Get spans for an error trace                     |
| `POST` | `/api/v2/tracing/traces/performance`  | List performance traces                          |
| `POST` | `/api/v2/tracing/traces/errors`       | List error traces                                |
| `POST` | `/api/v2/tracing/actions`             | List performance actions with aggregated metrics |
| `POST` | `/api/v2/tracing/action_edges`        | List upstream and downstream edges for an action |
| `POST` | `/api/v2/tracing/site_edges`          | List service dependency edges for a site         |
| `POST` | `/api/v2/tracing/slow_events`         | List slow events with aggregated stats           |
| `POST` | `/api/v2/tracing/slow_events/actions` | List actions related to a slow event             |

See the [tracing reference](/api/v2/traces).

### Logs

| Method | Path                 | Description      |
| ------ | -------------------- | ---------------- |
| `POST` | `/api/v2/logs/lines` | Search log lines |

See the [logs reference](/api/v2/logs).

### Kubernetes

| Method | Path                               | Description                               |
| ------ | ---------------------------------- | ----------------------------------------- |
| `POST` | `/api/v2/kubernetes/nodes`         | Query node metrics                        |
| `POST` | `/api/v2/kubernetes/pods`          | Query pod metrics                         |
| `POST` | `/api/v2/kubernetes/pods/overview` | Query pod overview with labels and status |

See the [Kubernetes reference](/api/v2/kubernetes).

### Deploys

| Method | Path                    | Description                          |
| ------ | ----------------------- | ------------------------------------ |
| `POST` | `/api/v2/deploys/stats` | Get deploy statistics for a revision |

See the [deploys reference](/api/v2/deploys).

### Check-ins

| Method | Path                          | Description                                  |
| ------ | ----------------------------- | -------------------------------------------- |
| `POST` | `/api/v2/check_ins/test_cron` | Test and validate a cron schedule expression |

See the [check-ins reference](/api/v2/check-ins).

### Saved visuals

| Method | Path                             | Description                     |
| ------ | -------------------------------- | ------------------------------- |
| `GET`  | `/api/v2/saved_visuals/{id}`     | Retrieve a saved visual as JSON |
| `GET`  | `/api/v2/saved_visuals/{id}/csv` | Download a saved visual as CSV  |

Saved visual endpoints do not require authentication. See the [saved visuals
reference](/api/v2/saved-visuals).

### System

| Method | Path           | Description                  |
| ------ | -------------- | ---------------------------- |
| `GET`  | `/api/v2/auth` | Verify that a token is valid |