Base URL
All endpoints are served under/api/v2 on the appsignal.com domain:
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.site_id. Some trace endpoints take a
site_ids array instead, 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.
Verify a token
message confirming the authenticated user ID.
Requests and responses
Most endpoints usePOST 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 a site_id or a site_ids array. The Kubernetes and service edge endpoints treat to as exclusive.
Machine-readable reference
/api/v2/openapi.json is the
API’s OpenAPI 3.1 spec, generated from the API’s code. It needs no token. Use it
to generate an API client, or to import the API into tools that read OpenAPI.
The endpoint reference pages in these docs are built from it.
Error responses
Any endpoint can return these non-2xx responses:
Trace, search, and log requests are limited to a few at a time per user. On
the trace list endpoints, a
429 can also include a suggestion: a faster way
to write the request’s filter. See List traces.
Error envelope
Every400 response uses the same envelope, so you can handle them in one place:
error: a stable, machine-readable slug. Branch on this in your code.message: a human-readable message, safe to display.details: optional data whose shape depends onerror.
pagination_invalid_per_page for an out-of-range
per_page. See Page through a list.
Endpoints
Metrics
For how to use them, see Querying metrics.
Tracing
For how to use them, see Querying traces.
Logs
For the query language, see Querying logs.
Search
For the query syntax, see Search traces.
Events
For how to use it, see Top events by group.
Kubernetes
Deploys
Check-ins
Saved visuals
Saved visual endpoints do not require authentication.