> ## 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.

# Trace

> Trace attributes, methods, and how to query stored traces from the database.

A `Trace` represents one complete agent execution from start to finish. Each trace has a unique `trace_id` that groups all related spans together.

## Trace Attributes

| Attribute | Type | Default | Description |
| - | - | - | - |
| `trace_id` | `str` | Required | Unique trace identifier |
| `name` | `str` | Required | Trace name (typically the root span name, e.g., `Agent.run`) |
| `status` | `str` | Required | Overall status: `OK`, `ERROR`, or `UNSET` |
| `duration_ms` | `int` | Required | Total execution time in milliseconds |
| `start_time` | `datetime` | Required | When the trace started |
| `end_time` | `datetime` | Required | When the trace completed |
| `total_spans` | `int` | Required | Total number of spans in this trace |
| `error_count` | `int` | Required | Number of spans that errored |
| `run_id` | `Optional[str]` | Required | Associated agent/team/workflow run ID (`None` when not set) |
| `session_id` | `Optional[str]` | Required | Associated session ID (`None` when not set) |
| `user_id` | `Optional[str]` | Required | Associated user ID (`None` when not set) |
| `agent_id` | `Optional[str]` | Required | Associated agent ID (`None` when not set) |
| `team_id` | `Optional[str]` | Required | Associated team ID (`None` when not set) |
| `workflow_id` | `Optional[str]` | Required | Associated workflow ID (`None` when not set) |
| `created_at` | `datetime` | Required | When the trace record was created |

## Methods

### `to_dict()`

Convert the trace to a dictionary.

```python theme={null}
trace_dict = trace.to_dict()
```

**Returns:** `dict`

### `from_dict()`

Create a trace from a dictionary.

```python theme={null}
trace = Trace.from_dict(data)
```

**Parameters:**

* `data` (`dict`): Dictionary containing trace data

**Returns:** `Trace`

## Usage

```python theme={null}
from agno.db.sqlite import SqliteDb

db = SqliteDb(db_file="tmp/traces.db")

# Get a trace
trace = db.get_trace(run_id=response.run_id)

if trace:
    print(f"Trace ID: {trace.trace_id}")
    print(f"Name: {trace.name}")
    print(f"Duration: {trace.duration_ms}ms")
    print(f"Status: {trace.status}")
    print(f"Total Spans: {trace.total_spans}")
    print(f"Errors: {trace.error_count}")
```

## See Also

* [Span Reference](https://agno-v2.mintlify.site/reference/tracing/span.md) - Individual operations within a trace
* [DB Functions](https://agno-v2.mintlify.site/tracing/db-functions.md) - Query functions for traces and spans


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.