AppSignal V2 API Documentation

REST API for metrics, traces, logs, Kubernetes monitoring, and deployment tracking.

Authentication

Most endpoints require a token. Pass it in one of two ways:

• Authorization header: Authorization: Bearer <token>
• Query parameter: ?token=<token>

Endpoints marked no auth do not require a token.

Error Responses

Endpoints return these unless they document their own:

Metrics

{
  "query": {
    "site_id": "abc123",
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-08T00:00:00Z",
    "resolution": "HOURLY",
    "select": [
      {
        "name": "disk_usage",
        "field": "GAUGE",
        "tags": {
          "hostname": "server-1"
        }
      }
    ]
  },
  "detector": "trend",
  "config": {
    "ceiling": 100
  }
}

{
  "site_id": "abc123",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z",
  "select": [
    {
      "id": "cpu",
      "name": "cpu",
      "field": "GAUGE",
      "tags": {
        "hostname": "*"
      }
    }
  ],
  "group_by": [
    {
      "Tag": "hostname"
    }
  ]
}

[
  "cpu",
  "disk_io",
  "memory",
  "network_tx"
]

{
  "site_id": "abc123",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z",
  "resolution": "MINUTELY",
  "select": [
    {
      "name": "cpu",
      "field": "GAUGE",
      "tags": {
        "hostname": "server-1",
        "state": "user"
      }
    }
  ]
}

{
  "metric_type": "GAUGE",
  "available_tags": [
    [
      "hostname"
    ],
    [
      "hostname",
      "state"
    ]
  ]
}

Tracing

{
  "site_id": "abc123",
  "namespace": "PublicApi/web",
  "action": "UsersController#show",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z"
}

{
  "upstream": [
    {
      "site_id": "def456",
      "site_name": "Frontend",
      "site_environment": "production",
      "service": "Frontend",
      "namespace": "web",
      "action": "HomeController#index",
      "caller_kind": "CLIENT",
      "callee_kind": "SERVER",
      "edge_type": "SYNC",
      "count": 1200,
      "error_count": 3,
      "mean": 42.5,
      "p_90": 80.1,
      "p_95": 110.7
    }
  ],
  "downstream": []
}

{
  "site_id": "abc123",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z",
  "namespaces": [
    "web"
  ]
}

[
  {
    "namespace": "web",
    "action": "UsersController#show",
    "digest": "a1b2c3",
    "mean": 123.4,
    "throughput": 5200.0,
    "error_rate": 0.8,
    "has_npo": false
  }
]

{
  "site_ids": [
    "abc123"
  ],
  "trace_id": "5baa0559ff2f4d35f3b2cd90d312bac3"
}

{
  "performance": [
    {
      "site_id": "abc123",
      "namespace": "web",
      "action_name": "POST /api/users"
    }
  ],
  "errors": [
    {
      "site_id": "abc123",
      "incident_number": 42,
      "exception_name": "RuntimeError",
      "incident_digests": [
        "1234567890"
      ]
    }
  ]
}

{
  "site_id": "abc123",
  "incident_digests": [
    "1023993"
  ],
  "from": "2024-01-01T00:00:00Z",
  "group_by": "VALUE",
  "metadata_key": "hostname"
}

[
  {
    "key": "frontend1",
    "value": 42
  }
]

{
  "site_id": "abc123",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z"
}

{
  "upstream": [],
  "downstream": [
    {
      "site_id": "def456",
      "site_name": "Billing",
      "site_environment": "production",
      "service": "Billing",
      "count": 800,
      "error_count": 2,
      "mean": 35.2,
      "p_90": 70.0,
      "p_95": 95.3
    }
  ],
  "internal": []
}

{
  "site_id": "abc123",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z",
  "wanted_attributes": {
    "payload": {
      "Required": [
        "db.query.text",
        "db.statement"
      ]
    },
    "system": {
      "Optional": [
        "db.system.name"
      ]
    }
  }
}

[
  {
    "digest": "1234567890",
    "count": 42,
    "mean": 125.5,
    "impact": 5271.0,
    "payload": "SELECT * FROM users WHERE id = ?",
    "system": "postgresql"
  }
]

{
  "site_id": "abc123",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z",
  "digest": "1234567890"
}

[
  {
    "action_name": "UsersController#index",
    "namespace": "web",
    "count": 42,
    "trace_id": "0af7651916cd43dd8448eb211c80319c",
    "start_time": "2024-01-01 00:00:00.123456789"
  }
]

{
  "site_ids": [
    "abc123"
  ],
  "trace_id": "5baa0559ff2f4d35f3b2cd90d312bac3"
}

{
  "site_ids": [
    "abc123"
  ],
  "digests": [
    "1234567890"
  ],
  "trace_id": "last"
}

{
  "site_ids": [
    "abc123"
  ],
  "namespace": "web",
  "action_name": "POST /api/users",
  "trace_id": "last"
}

{
  "site_ids": [
    "abc123"
  ],
  "digests": [
    "1234567890"
  ],
  "pagination": {
    "per_page": 50,
    "order": "DESC",
    "cursor": {
      "time": null
    }
  }
}

{
  "site_ids": [
    "abc123"
  ],
  "namespace": "web",
  "action_name": "POST /api",
  "duration_ms": 1000,
  "pagination": {
    "per_page": 50,
    "order": "DESC",
    "cursor": {
      "time": null
    }
  }
}

Events

{
  "site_id": "6591f2705fa150d75339e232",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z",
  "resolution": "HOURLY",
  "groups": [
    "active_record",
    "moped"
  ],
  "order": "IMPACT"
}

Search

{
  "site_ids": [
    "6591f2705fa150d75339e232"
  ],
  "query": "error:RuntimeError",
  "kind": "exception",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-02T00:00:00Z"
}

Logs

{
  "site_id": "abc123",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z",
  "source_ids": [
    "source-1",
    "source-2"
  ],
  "query": "error",
  "pagination": {
    "per_page": 50,
    "order": "DESC",
    "cursor": {
      "time": null,
      "id": null
    }
  }
}

Kubernetes

{
  "site_id": "abc123",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z",
  "node_name": "node-1"
}

{
  "site_id": "abc123",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z",
  "namespaces": [
    "default",
    "kube-system"
  ],
  "state": "Running"
}

{
  "site_id": "abc123",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-01T01:00:00Z",
  "namespaces": [
    "default"
  ],
  "query": "nginx"
}

Deploys

{
  "site_id": "6591f2705fa150d75339e232",
  "revision": "abc-123",
  "namespace": "web"
}

{
  "throughput": 1001,
  "mean": 1.95,
  "error_rate": 1.05
}

Check-ins

{
  "cron": "0 6 * * *",
  "wait_time_minutes": 5,
  "timestamp": 1614556800,
  "timezone": "Europe/Amsterdam"
}

{
  "now": "2021-03-01T00:00:00Z",
  "next_start": null,
  "next_end": null,
  "error": "Invalid cron error: Invalid pattern: ..."
}

{
  "now": "2021-03-01T00:00:00Z",
  "next_start": "2021-03-01T05:00:00Z",
  "next_end": "2021-03-01T05:05:00Z",
  "error": null
}

Saved Visuals

{
  "id": "60f3b3b3b3b3b3b3b3b3b3b3",
  "resolution": "HOURLY",
  "value_format": "number",
  "value_input": null,
  "series": [
    {
      "color": "rgb(0,0,0)",
      "name": "test",
      "renderer": "line",
      "data": [
        {
          "x": "2020-04-12T22:10:57Z",
          "y": 1.0
        }
      ]
    }
  ]
}

timestamp,line one,line two
2020-04-12T22:00:00+00:00,1,10
2020-04-12T22:01:00+00:00,0,10
2020-04-12T22:02:00+00:00,1,0

System

{
  "message": "Authenticated user 6694fca622fa81b8dd2e7178"
}

Type Reference

ActionEdge (object)

A single edge in the upstream or downstream list.

ActionEdgesApiQuery (object)

Query parameters for listing upstream and downstream action edges.

ActionEdgesResponse (object)

Response shape for the action edges endpoint.

ActionRow (object)

A single row in the actions list response, representing aggregated metrics for one namespace/action/digest combination.

ActionsParams (object)

Identifies the slow event whose actions to list.

ActionsQuery (object)

Query parameters for listing performance actions with aggregated metrics.

Aggregation (enum)

The aggregation function applied when combining multiple values within a time bucket.

Serialized as uppercase strings (e.g. "SUM", "AVERAGE"). When no aggregation is explicitly set on a selector, a default is chosen based on the Field type.

"SUM" | "AVERAGE" | "MIN" | "MAX" | "FIRST" | "LAST"

AnomalyConfig (object)

Detector tuning for one anomaly run; each detector reads only its own fields.

AnomalyPoint (object)

A single anomalous point flagged by a point-anomaly detector (e.g. spike).

The changepoint detector reuses this struct to describe a detected level shift, reinterpreting the fields: at is the shift boundary, baseline the robust level *before* the shift, value the robust level *after* it, and z_score the MAD-scaled shift magnitude (sign = direction: positive = stepped up, negative = stepped down).

The rate detector likewise reuses it for an anomalous rate bucket: at is the bucket, value the observed rate (numerator / denominator), baseline the robust baseline rate, and z_score the one-sample proportion z (sign = direction: positive = rate rose, negative = fell).

AnomalyRequest (object)

The series to analyse, the detector to run and its tuning.

AnomalyResponse (object)

The analysed series and its detections.

AttributeRequirement (one of)

Whether a group of attribute keys filters the slow events or is only returned.

AuthResponse (object)

Response body for the authentication test endpoint.

{
  "message": "Authenticated user 6694fca622fa81b8dd2e7178"
}

BadRequestResponse (object)

Standard body for HTTP 400 Bad Request responses. Branch on the stable error slug, display message as-is, and read per-error structured data from details.

Container (object)

A container within a Kubernetes pod.

ContainerStatus (enum)

Status of a container within a pod.

"Running" | "Terminated" | "Waiting" | "Unknown"

CronQuery (object)

Request body for testing a cron schedule expression.

CronQueryResult (object)

Result of evaluating a cron schedule expression.

DataPointOut (object)

A single data point in a saved visual series.

DeployStatsResult (object)

Aggregated metrics for one deployment. Without recorded samples, throughput is the error count, error_rate 100 (0 without errors) and mean 0.

Detection (object)

A single anomaly detected on one series.

DetectorKind (enum)

Which detection algorithm produced (or is requested to produce) a result.

"trend" | "spike" | "changepoint" | "time_to_threshold" | "rate"

ErrorLocation (object)

Error incident where a trace appears.

ErrorResponse (object)

Error body returned for 401, 404 and 500 responses.

ErrorTraceQuery (object)

The error incident whose trace to fetch.

ErrorTracesQuery (object)

Filters and pagination for listing the traces of error incidents.

EventGroupItem (object)

One event in the event group list.

EventGroupListQuery (object)

Query for the event group list.

EventGroupOrder (enum)

Field the event group list is ranked and truncated by.

"IMPACT" | "MEAN" | "THROUGHPUT"

Field (enum)

The specific measurement within a metric to retrieve.

A gauge metric only has a Gauge field; a counter metric only has a Counter field; a measurement metric has statistical fields such as Mean, Count, Min, Max and percentiles.

Serialized as uppercase strings (e.g. "GAUGE", "P95").

"GAUGE" | "COUNTER" | "MEAN" | "COUNT" | "MIN" | "MAX" | "P99" | "P95" | "P90" | "P80" | "P75" | "P70" | "P60" | "P50" | "P40" | "P30" | "P20" | "P10"

FillMode (enum)

How missing data points (empty time buckets) are filled when assembling a series.

"ZERO" | "PREVIOUS" | "NONE"

GroupBy (one of)

Specifies how rows in a List are grouped.

IncidentErrorRow (object)

A single incident digest's error count within the queried selection.

IncidentErrorsQuery (object)

Query for the incident error list.

IncidentKind (enum)

Whether something represents an exception or a performance incident.

"exception" | "performance"

List (object)

A tabular collection of Rows, returned for list-view queries.

Each row represents an aggregated metric value grouped by tags, used for displaying metric data in table format in the frontend.

ListQuery (object)

Query for fetching aggregated metric data in tabular form, used to populate list views.

Unlike TimeseriesQuery, which returns data points over time, a ListQuery returns one Row per unique combination of group-by values, with each row containing aggregated metric values.

ListSelector (object)

Selects a specific metric, field and tag combination to include in a list response.

Each selector contributes one entry in the resulting Row::data map, keyed by id.

LocatorQuery (object)

The trace to locate and the sites to search.

LogLine (object)

A log line; its attributes live inside json.

LogStreamEvent (one of)

One server-sent event of a streamed log search, as the JSON data of the event.

LogsQueryParams (object)

Filters and pagination for searching log lines.

MetadataDistributions (one of)

A bare JSON array of key rows or value rows.

MetadataDistributionsQuery (object)

Query for the metadata distribution list.

MetadataGroupBy (enum)

Which dimension the metadata distribution query groups by.

"KEY" | "VALUE"

MetadataKeyDistribution (object)

A single metadata key row (KEY mode).

MetadataValueDistribution (object)

A single metadata value row (VALUE mode).

MetricType (enum)

The category of a metric, which determines how its values are interpreted.

Serialized as uppercase strings (e.g. "GAUGE", "COUNTER", "MEASUREMENT").

"GAUGE" | "COUNTER" | "MEASUREMENT"

MetricTypeAndTags (object)

Metadata describing a metric's type and the tag combinations it can be queried with.

Used to communicate which timeseries are available for a given metric name, so consumers know what tags they can filter or group by.

NodesQuery (object)

Query for fetching Kubernetes node metrics.

NodesRow (object)

The latest Kubernetes node metrics within the requested time range.

Order (enum)

Sort order for query results

Used across multiple domains for paginated and ordered queries.

"ASC" | "DESC"

OwnerReference (object)

A Kubernetes owner reference linking a pod to its controller.

Pagination_LogPagination (object)

Keyset pagination settings, generic over each domain's cursor type.

Pagination_MetricsPagination (object)

Keyset pagination settings, generic over each domain's cursor type.

Pagination_TracePagination (object)

Keyset pagination settings, generic over each domain's cursor type.

PerformanceLocation (object)

Performance action where a trace appears.

PerformanceTraceQuery (object)

The performance action whose trace to fetch.

PerformanceTracesQuery (object)

Filters and pagination for listing the performance traces of one action.

PodOverviewRow (object)

A Kubernetes pod overview with metadata and status information.

PodOverviewsQuery (object)

Query for fetching Kubernetes pod overview data.

PodPhase (enum)

Kubernetes pod lifecycle phase.

"Running" | "Succeeded" | "Pending" | "Failed" | "Unknown"

PodState (enum)

Derived state of a pod, combining phase and container statuses.

"Unknown" | "Pending" | "Running" | "Succeeded" | "Failed"

PodsQuery (object)

Query for fetching detailed Kubernetes pod metrics.

PodsRow (object)

The latest detailed Kubernetes pod metrics within the requested time range.

Point (object)

A single data point in a timeseries, representing a value at a specific moment in time.

Projection (object)

A forward projection of a fitted linear trend toward a ceiling.

QueryProgress (object)

Progress of a log search, which runs over the time range in chunks.

RelatedTraceItem (object)

Related trace item showing an action where a slow event appears.

Resolution (enum)

Time resolution that metrics can be returned in

"HOURLY" | "MINUTELY" | "DAILY"

Row (object)

A single row in a List, representing aggregated metric values for one group of tags.

Rows from different metric sources can be merged together using Row::merge, combining their data maps into a single row.

SampleKind (enum)

Specifies whether to search errors, performance samples, or both.

"all" | "exception" | "performance"

SavedVisualOut (object)

JSON response representation of a saved visual (chart).

SearchRequest (object)

Request body for the unified search endpoint. Legacy samples match from and to by their minute or hour bucket rather than their exact time.

SearchResult (object)

A search result item returned by the unified search endpoint.

SearchResultSource (enum)

Whether a search result originates from an OpenTelemetry trace or a legacy sample.

"trace" | "sample"

Serie (object)

A single timeseries: a named sequence of points that share the same tags and field.

SerieOut (object)

A single data series within a saved visual.

Severity (enum)

Severity bucket for a detection, derived from how imminent / large the anomaly is.

"info" | "warning" | "critical"

SiteEdge (object)

A single service-level edge for the site dependency map. Unlike ActionEdge, this is aggregated across all actions in a service and carries no namespace or action name.

SiteEdgesApiQuery (object)

Query parameters for listing site-level service dependency edges.

SiteEdgesResponse (object)

Response shape for the site edges endpoint.

SlowEventItem (object)

A slow event aggregation (e.g. a slow database query).

SlowEventsParams (object)

Filters for listing slow events such as slow database queries.

SpanKind (enum)

The OpenTelemetry kind of a span, as a PascalCase string.

Client and Server are synchronous calls; Producer and Consumer are async jobs.

"Client" | "Server" | "Internal" | "Producer" | "Consumer"

StatsQuery (object)

Query for the aggregated metrics of one deployment revision, over all retained data.

Timeseries (object)

A collection of series over a time range, aligned to the given resolution.

TimeseriesQuery (object)

Query for fetching timeseries metric data, used to populate graphs.

TimeseriesSelector (object)

Selects a specific metric, field and tag combination to include in a timeseries response.

TooManyRequestsResponse (object)

Error body returned for 429 responses.

Trace (object)

A trace summary representing a root span.

TraceLocation (object)

Locations of a trace in performance and error contexts.

TraceQuery (object)

The trace to fetch and the sites to search.

TraceSpan (object)

A complete span with all its attributes, events and links.