> For the complete documentation index, see [llms.txt](https://docs.otari.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otari.ai/otari/for-integrators/api-reference/traces.md).

# Traces

## List Traces

> List agent sessions, most recently active first unless \`\`sort\`\` says otherwise.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"TraceListPublic":{"properties":{"has_more":{"title":"Has More","type":"boolean"},"items":{"items":{"$ref":"#/components/schemas/TraceSummaryPublic"},"title":"Items","type":"array"}},"required":["items","has_more"],"title":"TraceListPublic","type":"object"},"TraceSummaryPublic":{"description":"One agent session as the session list shows it.","properties":{"api_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Id"},"cost":{"description":"USD, a snapshot of the usage rows' cost. Usage stays the billing record.","title":"Cost","type":"number"},"error_count":{"description":"Spans that ended in an error no fallback recovered, including tools' errors, which do not fail the session.","title":"Error Count","type":"integer"},"harness":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The agent or client that sent the requests, from its User-Agent.","title":"Harness"},"input_tokens":{"title":"Input Tokens","type":"integer"},"last_activity_at":{"format":"date-time","title":"Last Activity At","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"output_tokens":{"title":"Output Tokens","type":"integer"},"session_source":{"description":"What grouped the session's requests: the client's own id, its agent harness's id, an OTLP conversation id, or nothing (a single request).","enum":["client","harness","otlp","none"],"title":"Session Source","type":"string"},"span_count":{"title":"Span Count","type":"integer"},"started_at":{"format":"date-time","title":"Started At","type":"string"},"step_count":{"description":"Requests the gateway served in the session.","title":"Step Count","type":"integer"},"trace_id":{"title":"Trace Id","type":"string"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"workspace_id":{"format":"uuid","title":"Workspace Id","type":"string"}},"required":["trace_id","workspace_id","user_id","api_key_id","session_source","harness","name","started_at","last_activity_at","step_count","span_count","error_count","input_tokens","output_tokens","cost"],"title":"TraceSummaryPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/traces":{"get":{"description":"List agent sessions, most recently active first unless ``sort`` says otherwise.","operationId":"traces-list_traces","parameters":[{"in":"query","name":"skip","required":false,"schema":{"default":0,"minimum":0,"title":"Skip","type":"integer"}},{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"title":"Limit","type":"integer"}},{"description":"What to order by. Latency runs from a session's start to its last activity.","in":"query","name":"sort","required":false,"schema":{"default":"last_activity","description":"What to order by. Latency runs from a session's start to its last activity.","enum":["last_activity","latency","tokens","cost","errors"],"title":"Sort","type":"string"}},{"description":"The direction of `sort`.","in":"query","name":"order","required":false,"schema":{"default":"desc","description":"The direction of `sort`.","enum":["asc","desc"],"title":"Order","type":"string"}},{"description":"Only sessions in this workspace. Narrows the caller's scope; never widens it.","in":"query","name":"workspace_id","required":false,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"Only sessions in this workspace. Narrows the caller's scope; never widens it.","title":"Workspace Id"}},{"description":"Sessions active at or after this instant (ISO 8601).","in":"query","name":"start","required":false,"schema":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Sessions active at or after this instant (ISO 8601).","title":"Start"}},{"description":"Sessions started before this instant (ISO 8601).","in":"query","name":"end","required":false,"schema":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Sessions started before this instant (ISO 8601).","title":"End"}},{"description":"Owning users.","in":"query","name":"user_id","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"maxItems":50,"type":"array"},{"type":"null"}],"description":"Owning users.","title":"User Id"}},{"description":"API keys.","in":"query","name":"api_key_id","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"maxItems":50,"type":"array"},{"type":"null"}],"description":"API keys.","title":"Api Key Id"}},{"description":"Agent harnesses.","in":"query","name":"harness","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"maxItems":50,"type":"array"},{"type":"null"}],"description":"Agent harnesses.","title":"Harness"}},{"description":"What grouped the session.","in":"query","name":"session_source","required":false,"schema":{"anyOf":[{"items":{"enum":["client","harness","otlp","none"],"type":"string"},"maxItems":4,"type":"array"},{"type":"null"}],"description":"What grouped the session.","title":"Session Source"}},{"description":"Only sessions with, or without, an unrecovered error.","in":"query","name":"has_error","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Only sessions with, or without, an unrecovered error.","title":"Has Error"}},{"description":"Part of a trace id, session name, harness or user id, in any case.","in":"query","name":"q","required":false,"schema":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"description":"Part of a trace id, session name, harness or user id, in any case.","title":"Q"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceListPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Traces","tags":["traces"]}}}}
```

## Count Traces

> Count the agent sessions that match.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"TraceCountPublic":{"properties":{"count":{"title":"Count","type":"integer"}},"required":["count"],"title":"TraceCountPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/traces/count":{"get":{"description":"Count the agent sessions that match.","operationId":"traces-count_traces","parameters":[{"description":"Only sessions in this workspace. Narrows the caller's scope; never widens it.","in":"query","name":"workspace_id","required":false,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"Only sessions in this workspace. Narrows the caller's scope; never widens it.","title":"Workspace Id"}},{"description":"Sessions active at or after this instant (ISO 8601).","in":"query","name":"start","required":false,"schema":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Sessions active at or after this instant (ISO 8601).","title":"Start"}},{"description":"Sessions started before this instant (ISO 8601).","in":"query","name":"end","required":false,"schema":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Sessions started before this instant (ISO 8601).","title":"End"}},{"description":"Owning users.","in":"query","name":"user_id","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"maxItems":50,"type":"array"},{"type":"null"}],"description":"Owning users.","title":"User Id"}},{"description":"API keys.","in":"query","name":"api_key_id","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"maxItems":50,"type":"array"},{"type":"null"}],"description":"API keys.","title":"Api Key Id"}},{"description":"Agent harnesses.","in":"query","name":"harness","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"maxItems":50,"type":"array"},{"type":"null"}],"description":"Agent harnesses.","title":"Harness"}},{"description":"What grouped the session.","in":"query","name":"session_source","required":false,"schema":{"anyOf":[{"items":{"enum":["client","harness","otlp","none"],"type":"string"},"maxItems":4,"type":"array"},{"type":"null"}],"description":"What grouped the session.","title":"Session Source"}},{"description":"Only sessions with, or without, an unrecovered error.","in":"query","name":"has_error","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Only sessions with, or without, an unrecovered error.","title":"Has Error"}},{"description":"Part of a trace id, session name, harness or user id, in any case.","in":"query","name":"q","required":false,"schema":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"description":"Part of a trace id, session name, harness or user id, in any case.","title":"Q"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceCountPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Count Traces","tags":["traces"]}}}}
```

## Trace Of Request

> The session a gateway request was traced into, by the \`\`Otari-Request-ID\`\` it was sent.\
> \
> The usage log's \`\`request\_group\_id\`\` is that id, so a request log row opens its\
> session here. A request outside the scope, or with no trace stored, is a 404.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"TraceSummaryPublic":{"description":"One agent session as the session list shows it.","properties":{"api_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Id"},"cost":{"description":"USD, a snapshot of the usage rows' cost. Usage stays the billing record.","title":"Cost","type":"number"},"error_count":{"description":"Spans that ended in an error no fallback recovered, including tools' errors, which do not fail the session.","title":"Error Count","type":"integer"},"harness":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The agent or client that sent the requests, from its User-Agent.","title":"Harness"},"input_tokens":{"title":"Input Tokens","type":"integer"},"last_activity_at":{"format":"date-time","title":"Last Activity At","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"output_tokens":{"title":"Output Tokens","type":"integer"},"session_source":{"description":"What grouped the session's requests: the client's own id, its agent harness's id, an OTLP conversation id, or nothing (a single request).","enum":["client","harness","otlp","none"],"title":"Session Source","type":"string"},"span_count":{"title":"Span Count","type":"integer"},"started_at":{"format":"date-time","title":"Started At","type":"string"},"step_count":{"description":"Requests the gateway served in the session.","title":"Step Count","type":"integer"},"trace_id":{"title":"Trace Id","type":"string"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"workspace_id":{"format":"uuid","title":"Workspace Id","type":"string"}},"required":["trace_id","workspace_id","user_id","api_key_id","session_source","harness","name","started_at","last_activity_at","step_count","span_count","error_count","input_tokens","output_tokens","cost"],"title":"TraceSummaryPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/traces/requests/{request_id}":{"get":{"description":"The session a gateway request was traced into, by the ``Otari-Request-ID`` it was sent.\n\nThe usage log's ``request_group_id`` is that id, so a request log row opens its\nsession here. A request outside the scope, or with no trace stored, is a 404.","operationId":"traces-trace_of_request","parameters":[{"in":"path","name":"request_id","required":true,"schema":{"title":"Request Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceSummaryPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Trace Of Request","tags":["traces"]}}}}
```

## Trace Series

> Count the sessions active in each bucket, split by whether they failed.\
> \
> A session is active from its start to its last activity, so a long one counts in every bucket it ran\
> through. Here \`\`start\`\` and \`\`end\`\` bound the buckets: a session that began before\
> \`\`start\`\` or was still active at \`\`end\`\` counts in the buckets between them it overlaps. Buckets are\
> aligned to their size in UTC and only the populated ones are returned. A session failed when it holds an\
> unrecovered error other than a tool's. A tool's error goes back to the model, an MCP tool's included, so\
> a session whose only errors are tools' counts as succeeded.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"TraceSeriesPublic":{"properties":{"bucket":{"enum":["1m","5m","30m","hour","6h","day"],"title":"Bucket","type":"string"},"points":{"items":{"$ref":"#/components/schemas/TraceBucketPublic"},"title":"Points","type":"array"}},"required":["bucket","points"],"title":"TraceSeriesPublic","type":"object"},"TraceBucketPublic":{"properties":{"bucket":{"description":"Bucket start, ISO 8601 UTC.","title":"Bucket","type":"string"},"failed":{"description":"Sessions active in the bucket that hold an unrecovered error other than a tool's. A tool's error, an MCP tool's included, goes back to the model, so it alone does not fail a session.","title":"Failed","type":"integer"},"succeeded":{"description":"Sessions active in the bucket that did not fail.","title":"Succeeded","type":"integer"}},"required":["bucket","succeeded","failed"],"title":"TraceBucketPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/traces/series":{"get":{"description":"Count the sessions active in each bucket, split by whether they failed.\n\nA session is active from its start to its last activity, so a long one counts in every bucket it ran\nthrough. Here ``start`` and ``end`` bound the buckets: a session that began before\n``start`` or was still active at ``end`` counts in the buckets between them it overlaps. Buckets are\naligned to their size in UTC and only the populated ones are returned. A session failed when it holds an\nunrecovered error other than a tool's. A tool's error goes back to the model, an MCP tool's included, so\na session whose only errors are tools' counts as succeeded.","operationId":"traces-trace_series","parameters":[{"in":"query","name":"bucket","required":false,"schema":{"default":"hour","enum":["1m","5m","30m","hour","6h","day"],"title":"Bucket","type":"string"}},{"description":"Only sessions in this workspace. Narrows the caller's scope; never widens it.","in":"query","name":"workspace_id","required":false,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"Only sessions in this workspace. Narrows the caller's scope; never widens it.","title":"Workspace Id"}},{"description":"Sessions active at or after this instant (ISO 8601).","in":"query","name":"start","required":false,"schema":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Sessions active at or after this instant (ISO 8601).","title":"Start"}},{"description":"Sessions started before this instant (ISO 8601).","in":"query","name":"end","required":false,"schema":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Sessions started before this instant (ISO 8601).","title":"End"}},{"description":"Owning users.","in":"query","name":"user_id","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"maxItems":50,"type":"array"},{"type":"null"}],"description":"Owning users.","title":"User Id"}},{"description":"API keys.","in":"query","name":"api_key_id","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"maxItems":50,"type":"array"},{"type":"null"}],"description":"API keys.","title":"Api Key Id"}},{"description":"Agent harnesses.","in":"query","name":"harness","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"maxItems":50,"type":"array"},{"type":"null"}],"description":"Agent harnesses.","title":"Harness"}},{"description":"What grouped the session.","in":"query","name":"session_source","required":false,"schema":{"anyOf":[{"items":{"enum":["client","harness","otlp","none"],"type":"string"},"maxItems":4,"type":"array"},{"type":"null"}],"description":"What grouped the session.","title":"Session Source"}},{"description":"Only sessions with, or without, an unrecovered error.","in":"query","name":"has_error","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Only sessions with, or without, an unrecovered error.","title":"Has Error"}},{"description":"Part of a trace id, session name, harness or user id, in any case.","in":"query","name":"q","required":false,"schema":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"description":"Part of a trace id, session name, harness or user id, in any case.","title":"Q"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceSeriesPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Trace Series","tags":["traces"]}}}}
```

## Get Trace

> One agent session: its turns, and every span inside them.\
> \
> A trace outside the scope is a 404. Without \`\`workspace\_id\`\`, an id in more\
> than one of the caller's workspaces is a 409 rather than a guess.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"TraceDetailPublic":{"properties":{"gates":{"description":"Each agent guardrail gate a coding agent's hook reported, the ones that did something first.","items":{"$ref":"#/components/schemas/GateSummaryPublic"},"title":"Gates","type":"array"},"spans":{"items":{"$ref":"#/components/schemas/SpanPublic"},"title":"Spans","type":"array"},"state":{"enum":["active","idle"],"title":"State","type":"string"},"summary":{"$ref":"#/components/schemas/TraceSummaryPublic"},"tool_costs":{"description":"An estimate for each tool call between two priced model requests, in the order they were made.","items":{"$ref":"#/components/schemas/ToolCostPublic"},"title":"Tool Costs","type":"array"},"truncated":{"description":"True when the session holds more spans than one read returns.","title":"Truncated","type":"boolean"},"turns":{"items":{"$ref":"#/components/schemas/TurnPublic"},"title":"Turns","type":"array"}},"required":["summary","state","turns","spans","truncated","gates","tool_costs"],"title":"TraceDetailPublic","type":"object"},"GateSummaryPublic":{"description":"How often one agent guardrail gate ran in a session, by what it decided.","properties":{"blocked":{"description":"Checks where the gate stopped the agent.","title":"Blocked","type":"integer"},"enforcement":{"anyOf":[{"enum":["required","advisory"],"type":"string"},{"type":"null"}],"title":"Enforcement"},"flagged":{"description":"Checks an advisory gate failed; the agent went ahead.","title":"Flagged","type":"integer"},"gate_id":{"title":"Gate Id","type":"string"},"gate_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"From the guardrail's definition, when it was sent.","title":"Gate Type"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What the gate says when it fails, from the guardrail's definition.","title":"Message"},"origin":{"anyOf":[{"enum":["repo","user"],"type":"string"},{"type":"null"}],"description":"Whether the gate is the repository's (.otari/) or the user's own (~/.otari/).","title":"Origin"},"passed":{"title":"Passed","type":"integer"},"refused":{"description":"Checks where the gate could not decide and held the agent anyway.","title":"Refused","type":"integer"},"runs":{"description":"The moments the gate runs at (pre_tool_use.edit_target, stop.session, ...).","items":{"type":"string"},"title":"Runs","type":"array"},"span_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The check to open first: the earliest that did anything but pass. Null for a gate that never ran.","title":"Span Id"},"undecided":{"description":"Checks where the gate could not decide; the agent went ahead unchecked.","title":"Undecided","type":"integer"}},"required":["gate_id","passed","blocked","flagged","refused","undecided","span_id","gate_type","enforcement","message","runs","origin"],"title":"GateSummaryPublic","type":"object"},"SpanPublic":{"description":"One span of a session. Its content is empty unless the deployment keeps content.","properties":{"approximate":{"description":"True when the start was inferred rather than measured.","title":"Approximate","type":"boolean"},"attributes":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"}]},"title":"Attributes","type":"object"},"cache_read_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Input tokens read from the prompt cache.","title":"Cache Read Tokens"},"cache_write_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Input tokens written to the prompt cache.","title":"Cache Write Tokens"},"content":{"additionalProperties":{"type":"string"},"description":"What the span was about (prompt, command, file_path, gate.evidence, gate.detail), only where the deployment keeps content and the agent sent it. Empty otherwise.","title":"Content","type":"object"},"context_window":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The model's context window in tokens, where the catalog knows it. Null on a span that is not a model request, and for a model the catalog does not list.","title":"Context Window"},"cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Ms"},"end_time":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"End Time"},"error_class":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Class"},"input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The whole prompt, cached tokens included.","title":"Input Tokens"},"kind":{"title":"Kind","type":"string"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"name":{"title":"Name","type":"string"},"opens_turn":{"title":"Opens Turn","type":"boolean"},"operation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operation"},"origin":{"enum":["gateway","otlp"],"title":"Origin","type":"string"},"otel_span_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The OpenTelemetry span id an OTLP span was exported with, in lowercase hex. Null on a span the gateway recorded itself.","title":"Otel Span Id"},"otel_trace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The OpenTelemetry trace id an OTLP span was exported with, in lowercase hex. Null on a span the gateway recorded itself.","title":"Otel Trace Id"},"outcome":{"enum":["ok","error","unknown","blocked"],"title":"Outcome","type":"string"},"output_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Output Tokens"},"parent_span_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Span Id"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"reasoning_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Output tokens spent reasoning.","title":"Reasoning Tokens"},"recovered":{"title":"Recovered","type":"boolean"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"},"span_id":{"title":"Span Id","type":"string"},"start_time":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"Start Time"},"tool_call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Call Id"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"},"tool_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Type"}},"required":["span_id","parent_span_id","kind","origin","name","operation","start_time","end_time","duration_ms","approximate","outcome","recovered","error_class","opens_turn","model","provider","input_tokens","output_tokens","cache_read_tokens","cache_write_tokens","reasoning_tokens","context_window","cost","tool_name","tool_type","tool_call_id","request_id","otel_trace_id","otel_span_id","attributes","content"],"title":"SpanPublic","type":"object"},"TraceSummaryPublic":{"description":"One agent session as the session list shows it.","properties":{"api_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Id"},"cost":{"description":"USD, a snapshot of the usage rows' cost. Usage stays the billing record.","title":"Cost","type":"number"},"error_count":{"description":"Spans that ended in an error no fallback recovered, including tools' errors, which do not fail the session.","title":"Error Count","type":"integer"},"harness":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The agent or client that sent the requests, from its User-Agent.","title":"Harness"},"input_tokens":{"title":"Input Tokens","type":"integer"},"last_activity_at":{"format":"date-time","title":"Last Activity At","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"output_tokens":{"title":"Output Tokens","type":"integer"},"session_source":{"description":"What grouped the session's requests: the client's own id, its agent harness's id, an OTLP conversation id, or nothing (a single request).","enum":["client","harness","otlp","none"],"title":"Session Source","type":"string"},"span_count":{"title":"Span Count","type":"integer"},"started_at":{"format":"date-time","title":"Started At","type":"string"},"step_count":{"description":"Requests the gateway served in the session.","title":"Step Count","type":"integer"},"trace_id":{"title":"Trace Id","type":"string"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"workspace_id":{"format":"uuid","title":"Workspace Id","type":"string"}},"required":["trace_id","workspace_id","user_id","api_key_id","session_source","harness","name","started_at","last_activity_at","step_count","span_count","error_count","input_tokens","output_tokens","cost"],"title":"TraceSummaryPublic","type":"object"},"ToolCostPublic":{"description":"An estimate of what one tool call cost, from the model requests either side of it.","properties":{"calling":{"description":"Its share of the output of the request that called it.","title":"Calling","type":"number"},"calls_sharing_request":{"description":"Tool calls the request that called it made, sharing its output.","title":"Calls Sharing Request","type":"integer"},"calls_sharing_result":{"description":"Tool calls whose results arrived together, sharing that growth.","title":"Calls Sharing Result","type":"integer"},"later_requests":{"description":"The later requests that read its result again.","title":"Later Requests","type":"integer"},"rereading":{"description":"Reading its result again in later requests, until the context was compacted.","title":"Rereading","type":"number"},"result_tokens":{"description":"About how many tokens its result added to the context.","title":"Result Tokens","type":"integer"},"span_id":{"title":"Span Id","type":"string"},"subagent":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"What a subagent the call ran cost, exactly.","title":"Subagent"},"total":{"title":"Total","type":"number"},"writing":{"description":"Writing its result into the context, on the next request.","title":"Writing","type":"number"}},"required":["span_id","total","calling","writing","rereading","result_tokens","later_requests","calls_sharing_request","calls_sharing_result","subagent"],"title":"ToolCostPublic","type":"object"},"TurnPublic":{"description":"One user prompt and the steps it caused.","properties":{"cache_read_tokens":{"title":"Cache Read Tokens","type":"integer"},"continued":{"description":"True for steps a session started with before any prompt was seen.","title":"Continued","type":"boolean"},"cost":{"title":"Cost","type":"number"},"ended_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"Ended At"},"errors":{"title":"Errors","type":"integer"},"index":{"title":"Index","type":"integer"},"input_tokens":{"title":"Input Tokens","type":"integer"},"llm_calls":{"title":"Llm Calls","type":"integer"},"output_tokens":{"title":"Output Tokens","type":"integer"},"started_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"Started At"},"state":{"enum":["active","completed","failed","incomplete"],"title":"State","type":"string"},"step_ids":{"items":{"type":"string"},"title":"Step Ids","type":"array"},"tool_calls":{"title":"Tool Calls","type":"integer"}},"required":["index","state","continued","started_at","ended_at","step_ids","tool_calls","llm_calls","errors","input_tokens","output_tokens","cache_read_tokens","cost"],"title":"TurnPublic","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/traces/{trace_id}":{"get":{"description":"One agent session: its turns, and every span inside them.\n\nA trace outside the scope is a 404. Without ``workspace_id``, an id in more\nthan one of the caller's workspaces is a 409 rather than a guess.","operationId":"traces-get_trace","parameters":[{"in":"path","name":"trace_id","required":true,"schema":{"title":"Trace Id","type":"string"}},{"description":"The workspace the trace is in, as its list entry names it.","in":"query","name":"workspace_id","required":false,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"The workspace the trace is in, as its list entry names it.","title":"Workspace Id"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceDetailPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get Trace","tags":["traces"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.otari.ai/otari/for-integrators/api-reference/traces.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.