Skip to main content
POST
Search the spans

Authorizations

Authorization
string
header
required

A project token (apsio_pt_v0...), which reads exactly one project, or an OAuth access token issued for the API, which reads what its user can. Access tokens issued for Apsio's MCP server are accepted only from the MCP server itself.

Path Parameters

projectId
string
required
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"0192f3a4-0000-7000-8000-00000000a101"

Body

application/json
from
string<date-time>

Start, inclusive (RFC 3339). Defaults to 24 hours before to.

to
string<date-time>

End, exclusive (RFC 3339). Defaults to now.

app_id
string

Only this app of the project.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
filters
object[]
Maximum array length: 20
errors_only
boolean
default:false

Only failed spans: an error status, or an HTTP request that got a 5xx or no response.

min_duration_ms
number

Spans at least this long.

Required range: 0 <= x <= 86400000
max_duration_ms
number

Spans at most this long.

Required range: 0 <= x <= 86400000
root_only
boolean
default:false

Only spans without a parent: the first span of each trace on the device.

sort
enum<string>
default:recent

Newest first, or longest first.

Available options:
recent,
slowest
limit
integer
default:100
Required range: 1 <= x <= 200
cursor
string

The next_cursor of the previous page, with the same sort. Opaque.

Maximum string length: 1024

Response

The matching spans and their volume.

from
string
required

RFC 3339 time in UTC with up to nanosecond precision.

Example:

"2026-10-04T10:15:00.431000000Z"

to
string
required

RFC 3339 time in UTC with up to nanosecond precision.

Example:

"2026-10-04T10:15:00.431000000Z"

bucket_seconds
integer
required
retention_days
integer
required

Days of detail the project's plan keeps (D94); nothing older is read.

histogram
object[]
required

Only buckets with spans.

spans
object[]
required
next_cursor
string | null
required

Pass as cursor to get the next page; null on the last page.

sql
string
required

The spans query with its values, for reading. Not run as written.