Traces
Traces — 4 operations on https://api.hanzo.ai.
The REST reference for Traces — 4 operations, generated from the OpenAPI document.
| Base URL | https://api.hanzo.ai |
| Operations | 4 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
traces
GET /v1/traces/health
How many spans this deployment holds for your org
Reports the native trace store's live state for the calling tenant: the subsystem version and spans, the count actually held right now. Not a dependency probe — the store is in-process, so this answers 200 whenever the process is up.
The tenant is the gateway-minted X-Org-Id header, falling back to the deployment brand and then default.
GET /v1/traces/query
Recent spans for your org over a time range
Answers {count, spans}, newest first, filtered on each span's START time. start and end are nanosecond bounds where 0 — which is what an absent, empty or unparseable value becomes — means UNBOUNDED, so a malformed bound widens the listing instead of failing it. limit defaults to 100 when absent or non-positive.
It lists SPANS, not traces: several spans of one trace each count separately and each take a slot against limit. Assembling one trace is /v1/traces/trace. The tenant is the gateway-minted X-Org-Id header, falling back to the deployment brand and then default.
GET /v1/traces/trace
Every span of one trace — the waterfall
Answers {spans}: every span the org holds for the trace id in id, in the order they were appended, which is what a waterfall view renders. Unlike the other reads there is no count, no time range and no limit — a trace is addressed by id or not at all.
An id with no spans answers an EMPTY list, never a 404: the store cannot tell a trace that never existed from one whose spans retention has already dropped, so it does not pretend to. The tenant is the gateway-minted X-Org-Id header, falling back to the deployment brand and then default, and a trace id belonging to another org is simply not in this org's store.
POST /v1/traces/write
Append spans for your org
Takes {spans:[{traceId, spanId, parentId, name, startNs, endNs, attrs}]}, appends each, and answers {written} — the number of spans sent. Every span is indexed by its trace id as it lands, which is what makes the waterfall read possible without a second store.
Times are NANOSECONDS since the Unix epoch. Retention is a bounded ring of 1048576 spans per org: past that the OLDEST are evicted to keep the newest 1048576, and the trace index is rebuilt — so a long-lived trace can lose its early spans while its later ones survive, and a waterfall read is best-effort against retention, not a guarantee.
The tenant is the gateway-minted X-Org-Id header, falling back to the deployment brand and then default. A body that does not decode is 400.
How is this guide?