# Traces

Trace lookup endpoints.

## List traces

> List traces within the authenticated project.

```json
{"openapi":"3.1.0","info":{"title":"Maniac Inference Gateway API","version":"1.0.0"},"tags":[{"name":"Traces","description":"Trace lookup endpoints."}],"servers":[{"url":"https://platform.maniac.ai","description":"The Maniac API"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"API key in Authorization header using Bearer <token>."}},"schemas":{"TraceListRes":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Object type identifier.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/TraceListItem"},"type":"array","title":"Data","description":"Returned items."},"total":{"type":"integer","minimum":0,"title":"Total","description":"Total number of items available for this resource."}},"additionalProperties":false,"type":"object","required":["data","total"],"title":"TraceListRes","description":"List response for project-scoped traces."},"TraceListItem":{"properties":{"id":{"type":"string","title":"Id","description":"External trace identifier (`trace.id`)."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Optional trace name."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Optional trace source."},"first_seen":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Seen","description":"Timestamp of the first request recorded for this trace."},"last_seen":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Seen","description":"Timestamp of the most recent request recorded for this trace."},"request_count":{"type":"integer","minimum":0,"title":"Request Count","description":"Number of inference log rows recorded for this trace."},"container_count":{"type":"integer","minimum":0,"title":"Container Count","description":"Number of distinct containers involved in this trace."},"spend":{"type":"integer","minimum":0,"title":"Spend","description":"Total spend across all requests in this trace."},"success_count":{"type":"integer","minimum":0,"title":"Success Count","description":"Number of successful requests recorded for this trace."},"error_count":{"type":"integer","minimum":0,"title":"Error Count","description":"Number of errored requests recorded for this trace."}},"additionalProperties":false,"type":"object","required":["id","request_count","container_count","spend","success_count","error_count"],"title":"TraceListItem"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ManiacError","description":"Error payload."}},"additionalProperties":false,"type":"object","required":["error"],"title":"ErrorResponse","description":"Response body for errors."},"ManiacError":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code."},"message":{"type":"string","title":"Message","description":"Human-readable error message."},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"Additional error details."}},"additionalProperties":false,"type":"object","required":["code","message"],"title":"ManiacError","description":"Standard Maniac API error envelope.\n\nThis matches the shape already used by v2 auth (`detail={\"error\": {...}}`)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/traces":{"get":{"tags":["Traces"],"summary":"List traces","description":"List traces within the authenticated project.","operationId":"traces_list","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceListRes"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Too Many Requests","headers":{"X-RateLimit-Limit":{"description":"Request limit per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"501":{"description":"Not Implemented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a trace

> Fetch a single trace by external trace id (\`trace.id\`) within the authenticated project.

```json
{"openapi":"3.1.0","info":{"title":"Maniac Inference Gateway API","version":"1.0.0"},"tags":[{"name":"Traces","description":"Trace lookup endpoints."}],"servers":[{"url":"https://platform.maniac.ai","description":"The Maniac API"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"API key in Authorization header using Bearer <token>."}},"schemas":{"TraceRes":{"properties":{"id":{"type":"string","title":"Id","description":"External trace identifier (`trace.id`)."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Optional trace name."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Optional trace source."},"trace_context":{"anyOf":[{"$ref":"#/components/schemas/TraceContext"},{"type":"null"}],"description":"Most recent normalized trace context stored for this trace."},"first_seen":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Seen","description":"Timestamp of the first request recorded for this trace."},"last_seen":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Seen","description":"Timestamp of the most recent request recorded for this trace."},"request_count":{"type":"integer","minimum":0,"title":"Request Count","description":"Number of inference log rows recorded for this trace."},"container_count":{"type":"integer","minimum":0,"title":"Container Count","description":"Number of distinct containers involved in this trace."},"error_count":{"type":"integer","minimum":0,"title":"Error Count","description":"Number of errored requests recorded for this trace."},"spans":{"items":{"$ref":"#/components/schemas/TraceSpanRes"},"type":"array","title":"Spans","description":"Grouped spans for this trace."}},"additionalProperties":false,"type":"object","required":["id","request_count","container_count","error_count"],"title":"Trace"},"TraceContext":{"properties":{"id":{"type":"string","title":"Id","description":"External trace identifier used to group requests."},"span_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Span Id","description":"Optional span identifier within the trace."},"parent_span_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Span Id","description":"Optional parent span identifier."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Optional trace name."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Optional trace source, e.g. langchain."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Optional metadata associated with the trace."}},"additionalProperties":false,"type":"object","required":["id"],"title":"TraceContext"},"TraceSpanRes":{"properties":{"span_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Span Id","description":"Logical span identifier within the trace."},"parent_span_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Span Id","description":"Optional parent span identifier."},"first_seen":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Seen","description":"Timestamp of the first attempt recorded for this span."},"last_seen":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Seen","description":"Timestamp of the most recent attempt recorded for this span."},"attempt_count":{"type":"integer","minimum":0,"title":"Attempt Count","description":"Number of attempts recorded for this logical span."},"inference_log_ids":{"items":{"type":"string"},"type":"array","title":"Inference Log Ids","description":"Chronological list of inference log ids (`task_inference_logs.id`) for this span."},"latest_inference_log_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Inference Log Id","description":"Inference log id for the most recent attempt."},"latest_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Status","description":"Status for the most recent attempt."},"container_count":{"type":"integer","minimum":0,"title":"Container Count","description":"Number of distinct containers involved in this span."}},"additionalProperties":false,"type":"object","required":["attempt_count","container_count"],"title":"TraceSpan"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ManiacError","description":"Error payload."}},"additionalProperties":false,"type":"object","required":["error"],"title":"ErrorResponse","description":"Response body for errors."},"ManiacError":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code."},"message":{"type":"string","title":"Message","description":"Human-readable error message."},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"Additional error details."}},"additionalProperties":false,"type":"object","required":["code","message"],"title":"ManiacError","description":"Standard Maniac API error envelope.\n\nThis matches the shape already used by v2 auth (`detail={\"error\": {...}}`)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/traces/{id}":{"get":{"tags":["Traces"],"summary":"Get a trace","description":"Fetch a single trace by external trace id (`trace.id`) within the authenticated project.","operationId":"traces_retrieve","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","title":"Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceRes"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Too Many Requests","headers":{"X-RateLimit-Limit":{"description":"Request limit per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```