Traces
Create and list traces, and fetch a single trace with spans over HTTP.
Use the traces API to ingest observability data from your inference stack or to read back traces for debugging.
All paths below are relative to /api/v1/traces. Include authentication headers on every call.
Create trace
POST /api/v1/traces
- Body: JSON object accepted by the trace creation handler (spans, metadata, timing fields as supported by your workspace version).
- Success: JSON result containing identifiers and status information for the created trace.
Used by the TypeScript SDK and compatible exporters when sending completed or in-progress traces.
List traces
GET /api/v1/traces
Optional query parameters (all strings unless noted):
| Parameter | Type | Purpose |
|---|---|---|
projectId | string | Filter or scope listing when applicable. |
status | string | Filter by trace status when supported. |
limit | number | Maximum number of items to return (integer). |
cursor | string | Pagination cursor from a previous response. |
Responses are JSON. Use cursor and limit together for stable pagination in busy projects.
Advanced: args query blob
GET handlers also support a URL query parameter args whose value is JSON-encoded and merged into the server-side query arguments. Prefer explicit query keys above when they cover your use case; reserve args for advanced filtering supported by your deployment.
Get trace by id
GET /api/v1/traces/{id}
- Path:
idis the trace identifier. - Returns: JSON for the trace, including span data needed to render timelines in the product.
There is no documented DELETE on traces for end users; retention and deletion follow your organization’s product settings and support policies.