Skip to main content
GET
Query project traces

Authorizations

Authorization
string
header
required

Use a JWT bearer token or a Veryfront API key in the Authorization header.

Path Parameters

project_reference
string
required

Project slug or UUID. The resolved project is used to scope all trace reads server-side.

Query Parameters

start
string<date-time>

Start time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400.

end
string<date-time>

End time. ISO 8601 timestamp accepted by the Veryfront API. The backend converts it to the unix-second format required by Grafana Cloud Tempo. Traces are kept for 30 days and one search spans at most 30 days; an older start or a wider range returns 400.

limit
number
default:20

Max traces to return (default: 20, max: 100).

Required range: 1 <= x <= 100
service
string

Optional OpenTelemetry service.name filter, for example veryfront-api, veryfront-studio, or veryfront-server.

Maximum string length: 200
status
enum<string>

Optional Tempo status filter. Use ok, error, or unset. error matches traces with an error span of the project or without project context anywhere in the trace, as trace detail reports.

Available options:
ok,
error,
unset
min_duration_ms
number | null

Optional minimum trace duration in milliseconds.

Required range: x >= 0
run_id
string

Optional run ID. Returns traces with a span whose run.id, parent.run.id, or agent.run.id is this run, or that contain its runtime control-plane request.

Required string length: 1 - 200
sort_by
enum<string>
default:timestamp

Sort field. Defaults to "timestamp".

Available options:
timestamp,
duration,
status,
service
sort_order
enum<string>
default:desc

Sort order. Defaults to "desc".

Available options:
asc,
desc

Response

Trace query results

traces
object[]
required
stats
object
required