> ## Documentation Index > Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Get Trace or Span Detail > Retrieve detailed trace information with hierarchical span tree, or a specific span within the trace. **Without span_id parameter:** Returns the full trace with hierarchical span tree: - Trace metadata (ID, status, duration, context) - Hierarchical tree of all spans - Each span includes timing, status, and type-specific metadata **With span_id parameter:** Returns details for a specific span within the trace: - Span metadata (ID, name, type, timing) - Status and error information - Type-specific attributes (model, tokens, tool params, etc.) **Span Hierarchy (full trace):** The `tree` field contains root spans, each with potential `children`. This recursive structure represents the execution flow: ``` Agent.run (root) ├─ LLM.invoke ├─ Tool.execute │ └─ LLM.invoke (nested) └─ LLM.invoke ``` **Span Types:** - `AGENT`: Agent execution with input/output - `LLM`: Model invocations with tokens and prompts - `TOOL`: Tool calls with parameters and results ## OpenAPI ````yaml get /traces/{trace_id} openapi: 3.1.0 info: title: Agno API Reference description: The all-in-one, private, secure agent platform that runs in your cloud. version: 3.0.4 servers: [] security: [] paths: /traces/{trace_id}: get: tags: - Traces - Traces summary: Get Trace or Span Detail description: >- Retrieve detailed trace information with hierarchical span tree, or a specific span within the trace. **Without span_id parameter:** Returns the full trace with hierarchical span tree: - Trace metadata (ID, status, duration, context) - Hierarchical tree of all spans - Each span includes timing, status, and type-specific metadata **With span_id parameter:** Returns details for a specific span within the trace: - Span metadata (ID, name, type, timing) - Status and error information - Type-specific attributes (model, tokens, tool params, etc.) **Span Hierarchy (full trace):** The `tree` field contains root spans, each with potential `children`. This recursive structure represents the execution flow: ``` Agent.run (root) ├─ LLM.invoke ├─ Tool.execute │ └─ LLM.invoke (nested) └─ LLM.invoke ``` **Span Types:** - `AGENT`: Agent execution with input/output - `LLM`: Model invocations with tokens and prompts - `TOOL`: Tool calls with parameters and results operationId: get_trace parameters: - name: trace_id in: path required: true schema: type: string title: Trace Id - name: span_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Optional: Span ID to retrieve specific span' title: Span Id description: 'Optional: Span ID to retrieve specific span' - name: run_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Optional: Run ID to retrieve trace for' title: Run Id description: 'Optional: Run ID to retrieve trace for' - name: db_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Database ID to query trace from title: Db Id description: Database ID to query trace from responses: '200': description: Trace or span detail retrieved successfully content: application/json: schema: anyOf: - $ref: '#/components/schemas/TraceDetail' - $ref: '#/components/schemas/TraceNode' title: Response Get Trace examples: full_trace: summary: Full trace with hierarchy (no span_id) value: trace_id: a1b2c3d4 name: Stock_Price_Agent.run status: OK duration: 1.2s start_time: '2025-11-19T10:30:00.000000+00:00' end_time: '2025-11-19T10:30:01.200000+00:00' total_spans: 4 error_count: 0 input: What is Tesla stock price? output: The current price of Tesla (TSLA) is $245.67. run_id: run123 session_id: session456 user_id: user789 agent_id: stock_agent created_at: '2025-11-19T10:30:00+00:00' tree: - id: span1 name: Stock_Price_Agent.run type: AGENT duration: 1.2s status: OK spans: [] single_span: summary: Single span detail (with span_id) value: id: span2 name: gpt-4o-mini.invoke type: LLM duration: 800ms status: OK metadata: model: gpt-4o-mini input_tokens: 120 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' '403': description: 'Insufficient permissions. Required scope(s): traces:read' '404': description: Trace or span not found content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' security: - {} - HTTPBearer: [] components: schemas: TraceDetail: properties: trace_id: type: string title: Trace Id description: Unique trace identifier name: type: string title: Name description: Trace name (usually root span name) status: type: string title: Status description: Overall status (OK, ERROR) duration: type: string title: Duration description: Human-readable total duration start_time: type: string format: date-time title: Start Time description: Trace start time (Pydantic auto-serializes to ISO 8601) end_time: type: string format: date-time title: End Time description: Trace end time (Pydantic auto-serializes to ISO 8601) total_spans: type: integer title: Total Spans description: Total number of spans in this trace error_count: type: integer title: Error Count description: Number of spans with errors input: anyOf: - type: string - type: 'null' title: Input description: Input to the agent/workflow output: anyOf: - type: string - type: 'null' title: Output description: Output from the agent/workflow error: anyOf: - type: string - type: 'null' title: Error description: Error message if status is ERROR run_id: anyOf: - type: string - type: 'null' title: Run Id description: Associated run ID session_id: anyOf: - type: string - type: 'null' title: Session Id description: Associated session ID user_id: anyOf: - type: string - type: 'null' title: User Id description: Associated user ID agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: Associated agent ID team_id: anyOf: - type: string - type: 'null' title: Team Id description: Associated team ID workflow_id: anyOf: - type: string - type: 'null' title: Workflow Id description: Associated workflow ID created_at: type: string format: date-time title: Created At description: Time when trace was created (Pydantic auto-serializes to ISO 8601) tree: items: $ref: '#/components/schemas/TraceNode' type: array title: Tree description: Hierarchical tree of spans (root nodes) type: object required: - trace_id - name - status - duration - start_time - end_time - total_spans - error_count - created_at - tree title: TraceDetail description: Detailed trace information with hierarchical span tree TraceNode: properties: id: type: string title: Id description: Span ID name: type: string title: Name description: Span name (e.g., 'agent.run', 'llm.invoke') type: type: string title: Type description: Span kind (AGENT, TEAM, WORKFLOW, LLM, TOOL) duration: type: string title: Duration description: Human-readable duration (e.g., '123ms', '1.5s') start_time: type: string format: date-time title: Start Time description: Start time (Pydantic auto-serializes to ISO 8601) end_time: type: string format: date-time title: End Time description: End time (Pydantic auto-serializes to ISO 8601) status: type: string title: Status description: Status code (OK, ERROR) input: anyOf: - type: string - type: 'null' title: Input description: Input to the span output: anyOf: - type: string - type: 'null' title: Output description: Output from the span error: anyOf: - type: string - type: 'null' title: Error description: Error message if status is ERROR spans: anyOf: - items: $ref: '#/components/schemas/TraceNode' type: array - type: 'null' title: Spans description: Child spans in the trace hierarchy step_type: anyOf: - type: string - type: 'null' title: Step Type description: Workflow step type (Step, Condition, function, Agent, Team) metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Additional span attributes and data extra_data: anyOf: - additionalProperties: true type: object - type: 'null' title: Extra Data description: Flexible field for custom attributes and additional data type: object required: - id - name - type - duration - start_time - end_time - status title: TraceNode description: Recursive node structure for rendering trace hierarchy in the frontend BadRequestResponse: properties: detail: type: string title: Detail description: Human-readable error message error_id: anyOf: - type: string - type: 'null' title: Error Id description: >- Stable identifier for the specific error, present only when the error carries one error_type: anyOf: - type: string - type: 'null' title: Error Type description: Category of the error, present only when the error carries one type: object required: - detail title: BadRequestResponse example: detail: Bad request UnauthenticatedResponse: properties: detail: type: string title: Detail description: Human-readable error message error_id: anyOf: - type: string - type: 'null' title: Error Id description: >- Stable identifier for the specific error, present only when the error carries one error_type: anyOf: - type: string - type: 'null' title: Error Type description: Category of the error, present only when the error carries one type: object required: - detail title: UnauthenticatedResponse example: detail: Unauthenticated access NotFoundResponse: properties: detail: type: string title: Detail description: Human-readable error message error_id: anyOf: - type: string - type: 'null' title: Error Id description: >- Stable identifier for the specific error, present only when the error carries one error_type: anyOf: - type: string - type: 'null' title: Error Type description: Category of the error, present only when the error carries one type: object required: - detail title: NotFoundResponse example: detail: Not found ValidationErrorResponse: properties: detail: anyOf: - type: string - items: $ref: '#/components/schemas/ValidationErrorDetail' type: array title: Detail description: >- A single message for an explicitly raised 422, or a list of field-level errors for a request-validation failure type: object required: - detail title: ValidationErrorResponse description: >- 422 body. Two runtime shapes share this status code, and the same endpoint can return either, so ``detail`` is typed as their union: - FastAPI's request-validation handler emits a **list** of field-level errors (built-in coercion errors and custom-validator ``ValueError``s alike). - A route that raises ``HTTPException(status_code=422, detail="...")`` for a semantic check (e.g. an invalid cron expression) emits a **string** through the HTTPException handler. example: detail: - loc: - body - endpoint msg: Value error, Endpoint must be a path, not a full URL type: value_error InternalServerErrorResponse: properties: detail: type: string title: Detail description: Human-readable error message error_id: anyOf: - type: string - type: 'null' title: Error Id description: >- Stable identifier for the specific error, present only when the error carries one error_type: anyOf: - type: string - type: 'null' title: Error Type description: Category of the error, present only when the error carries one type: object required: - detail title: InternalServerErrorResponse example: detail: Internal server error ValidationErrorDetail: properties: loc: items: anyOf: - type: string - type: integer type: array title: Loc description: Path to the offending field, e.g. ['body', 'endpoint'] msg: type: string title: Msg description: Human-readable error message type: type: string title: Type description: Error type identifier, e.g. 'value_error' or 'missing' type: object required: - loc - msg - type title: ValidationErrorDetail description: >- One field-level error inside a 422 body, matching FastAPI's default shape. securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.