Lists the caller org's recent traces — one row per trace with its span count…

Lists the caller org's recent traces — one row per trace with its span count and wall-clock duration, most recently active first.

GET /v1/o11y/traces

O11y → · All API references → · Six flows, four surfaces →


Address	`https://api.hanzo.ai/v1/o11y/traces`
Method	`GET`
Operation	`get_o11y_traces`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Lists the caller org's recent traces — one row per trace with its span count and wall-clock duration, most recently active first. This is the trace SEARCH: it is where a trace id comes from, and the spans behind any row are then read from GET /v1/o11y/traces/{traceId}. Every row belongs to the caller's own org — the tenant is the validated principal, never an input, and there is no administrator widening, because a trace list is a tenant's records rather than a rollup over them. An unreachable telemetry store answers 503 rather than an empty page, because "no traces" and "cannot see the traces" are different facts and only one of them is about the caller's system.

Request

3 fields.

Field	In	Type	Required	Description
`range`	query	integer	—	Range is the window in seconds, counted back from now over each trace's last activity.
`limit`	query	integer	—	Limit is how many traces to return.
`minDurationMs`	query	integer	—	MinDurationMs keeps only traces that lasted at least this many milliseconds.

Response

Status	Body	Meaning
`200`	o11y.tracesOut	ok

200 body — 9 fields.

Field	In	Type	Always	Description
`count`	body	integer	—	Count is how many traces this page carries.
`limit`	body	integer	—	Limit is the page cap actually applied, after clamping.
`sinceSec`	body	integer	—	SinceSec is the window actually read, in seconds, after clamping.
`traces`	body	o11y.traceRow[]	—	Traces are the caller org's traces, most recently active first.
`traces[].durationMs`	body	number	—	DurationMs is End minus Start in milliseconds: the trace's wall clock, not the sum of its spans, which double-counts everything concurrent.
`traces[].end`	body	string	—	End is the latest span end, RFC3339 with nanoseconds, in UTC.
`traces[].numSpans`	body	integer	—	NumSpans is how many spans the trace carries.
`traces[].start`	body	string	—	Start is the earliest span start, RFC3339 with nanoseconds, in UTC.
`traces[].traceId`	body	string	—	TraceID is the trace's id — the {traceId} of the detail read.

Failure carries the platform error shape — see Errors.

Examples

hanzo o11y traces list

import { Configuration, O11yApi } from 'hanzoai';

const api = new O11yApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getO11yTraces();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import O11yApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = O11yApi(client).get_o11y_traces()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.O11yAPI.GetO11yTraces(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, o11y_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = o11y_api::get_o11y_traces(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.O11yApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new O11yApi(client).getO11yTraces();

curl https://api.hanzo.ai/v1/o11y/traces \
  -H "Authorization: Bearer $HANZO_API_KEY"

The door reaches o11y through the o11y tool, which names its 340 operations with its own verbs — this one among them, under a name only the door declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "get_o11y_alert_last"
         }
       }
     }'

O11y API · All Hanzo APIs · Interactive reference

Lists the caller org's recent traces — one row per trace with its span count…

Request

Response

Examples

On this page