Skip to main content
Read distributed tracing data with the Public API (V2). All endpoints authenticate with your personal API token. This page explains how the tracing endpoints fit together. For every field of each request and response, see the tracing endpoint reference. Some endpoints take a site_ids array, so they can search across multiple sites in one request. The others take a single site_id.

Locate a trace

Find the performance actions and error incidents a trace appears in, across sites.
The request body takes site_ids (a string array) and trace_id (a string). The response has performance entries, with the namespace and action_name, and errors entries, with the incident_number and exception_name. Each errors entry also has incident_digests. Pass them as digests to the error trace endpoints.

Get the spans of a trace

Return every span in a trace.
The request body takes site_ids (a string array) and trace_id (a string). To also return spans from other traces that link to this one, set include_linked_spans to true.
Two more endpoints return the spans of one trace without needing its ID:
  • POST /api/v2/tracing/trace/performance takes an action_name and a namespace.
  • POST /api/v2/tracing/trace/error takes the digests of an error incident.
Both return the most recent matching trace. To fetch a specific one instead, add its trace_id.

List traces

List performance or error traces.
The two endpoints take different filters:
  • traces/performance needs an action_name and a namespace. Add duration_ms to list only traces at least that long. Add from and to to set a time range.
  • traces/errors needs the digests of the error incidents. It has no time range.
Both accept an optional query to filter by revision or tag, and both need a pagination object.
pagination needs all three of these fields:
  • per_page: how many traces to return per page, up to 100.
  • order: ASC or DESC.
  • cursor: { "time": null } to sort by trace time, or { "duration": null } to sort by trace duration. null starts from the first page.
Each trace in the response has a trace_id, the time the trace started, and its total duration in milliseconds.
To filter on a tag that holds a full ID, use =, as in tag.request_id=<id>. A : is a much slower substring match: it reads every span with that tag in the time range. If such a request gets a 429 and the value is a UUID, the response’s suggestion shows the = form.

Search traces

Search errors and performance data across sites, by action, exception, tag, or message.
The body needs site_ids: at least one site, all in the same account. The optional query matches like this:
  • Bare words match an action name, exception name, or tag value exactly, as one phrase.
  • action:, error:, and tag: match one field exactly.
  • message: matches a whole-word phrase, ignoring case.
Quote values that contain spaces. To narrow the results, add a namespace, a from and to range, or a kind. kind is all (the default), exception, or performance. from defaults to the start of your account’s retention, and to defaults to now. The response holds up to limit results, newest first. limit defaults to 50 and is capped at 2,000. Each result is one incident digest of a matching span, so a trace_id can appear more than once.

List performance actions

List performance actions with aggregated metrics.
The request body takes site_id, from, to, and the optional namespaces (array), revision, and action filters. You get back an array of action rows, each with namespace, action, digest, mean (ms), throughput, error_rate (0–100), and has_npo (whether an N+1 query was detected).

Service dependency edges

Map distributed tracing relationships between actions and services.
action_edges returns the upstream (callers) and downstream (callees) edges for a focused action. Its body takes site_id, namespace (in "<service>/<namespace>" form, such as "PublicApi/web"), action, from, and to. site_edges returns upstream, downstream, and internal edges for a focused site. Its body takes site_id, from, and to. In both, from is inclusive and to is exclusive. Each edge reports the peer service, request count, error_count, mean (ms), and p_90 / p_95 durations. Action edges also include the peer namespace, action, the span kinds caller_kind and callee_kind, and edge_type (SYNC or ASYNC).

Slow events

Analyze slow operations within traces, such as slow database queries.
slow_events returns up to 100 aggregated slow events. Its body takes site_id, from, to, and wanted_attributes. You can also add these filters:
  • span_kind: only include one kind of span: Client, Server, Internal, Producer, or Consumer.
  • excluded_attributes: leave out spans that have any of the listed attribute keys.
wanted_attributes names the span attributes to return. Group them under lowercase names you choose, such as payload. Each group is either Required or Optional:
  • Required only includes spans where at least one of the listed keys has a value.
  • Optional returns the value when it is set, and does not filter spans.
When a group lists several keys, it returns the value of the first key that has one. Besides span attribute keys, a group can list appsignal.library. It returns the library that AppSignal instrumented the span with, such as active_record, and is empty for other spans. For example, "system": { "Optional": ["db.system.name", "db.system", "appsignal.library"] } returns the database system when the span records one, and the library otherwise. Spans stored before late July 2026 return it empty. The request needs at least one Required group, or it returns a 400. This request lists slow database queries, with the query text and the database system:
Each result has a digest, count, mean (ms), and impact score. Each group in wanted_attributes comes back as a key of its own, such as "payload": "SELECT * FROM users WHERE id = ?". slow_events/actions lists the actions a slow event appears in. Its body takes site_id, from, to, and the digest from slow_events. Each result has an action_name, namespace, and count, plus the trace_id and start_time of the most recent occurrence.

Top events by group

Rank the events in one or more event groups, such as active_record queries, by total time, mean duration, or throughput.
The body takes site_id, from, to, and groups: at least one event group, such as ["active_record", "moped"]. AppSignal widens from and to to whole resolution buckets. order ranks the events by IMPACT (the default), MEAN, or THROUGHPUT. limit accepts 1 to 1,000 rows and defaults to 1,000. Each row has the event’s digest, group, and name, such as sql.active_record. It has a title, and a body such as the query text. It also has the count, the mean duration in milliseconds, and the impact: the total time spent, count times mean. Some events are left out after ranking, so fewer rows than limit can come back.

Investigate error incidents

Count the errors of each incident, then see what the incidents have in common.
tracing/errors counts errors per incident. Its body takes site_id, from, and to, and you can filter by namespaces and revision. Each row has an incident_digest, its namespace and latest revision, and an error_count. The response includes every matching incident, unsorted. To find the incidents with the most errors, sort the rows by error_count. metadata_distributions breaks incidents down by their metadata, such as hostname. Its body takes site_id, the incident_digests to include, from, and group_by:
  • KEY lists each metadata key, with its total occurrences and the number of unique values.
  • VALUE lists the values of the key you set in metadata_key. In each row, key holds the value and value holds how often it occurs.
to defaults to now. limit accepts 1 to 1,000 rows. It defaults to 10 rows in VALUE mode, and to no limit in KEY mode. To see the traces behind an incident, pass its digest to traces/errors or trace/error.