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.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.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.
POST /api/v2/tracing/trace/performancetakes anaction_nameand anamespace.POST /api/v2/tracing/trace/errortakes thedigestsof an error incident.
trace_id.
List traces
List performance or error traces.traces/performanceneeds anaction_nameand anamespace. Addduration_msto list only traces at least that long. Addfromandtoto set a time range.traces/errorsneeds thedigestsof the error incidents. It has no time range.
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:ASCorDESC.cursor:{ "time": null }to sort by trace time, or{ "duration": null }to sort by trace duration.nullstarts from the first page.
trace_id, the time the trace started, and
its total duration in milliseconds.
Search traces
Search errors and performance data across sites, by action, exception, tag, or message.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:, andtag:match one field exactly.message:matches a whole-word phrase, ignoring case.
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.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, orConsumer.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:
Requiredonly includes spans where at least one of the listed keys has a value.Optionalreturns the value when it is set, and does not filter spans.
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:
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 asactive_record queries, by total time, mean duration, or throughput.
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:
KEYlists each metadata key, with itstotaloccurrences and the number ofuniquevalues.VALUElists the values of the key you set inmetadata_key. In each row,keyholds the value andvalueholds 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.