> For the complete documentation index, see [llms.txt](https://docs.maniac.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maniac.ai/api-reference/traces.md). # 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 ."}},"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 ."}},"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"}}}}}}}}} ``` --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.maniac.ai/api-reference/traces.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.