> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-studio-tools-doc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Trace

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`           | `0`      | Total number of spans in this trace                          |
| `error_count` | `int`           | `0`      | Number of spans that errored                                 |
| `run_id`      | `Optional[str]` | `None`   | Associated agent/team/workflow run ID                        |
| `session_id`  | `Optional[str]` | `None`   | Associated session ID                                        |
| `user_id`     | `Optional[str]` | `None`   | Associated user ID                                           |
| `agent_id`    | `Optional[str]` | `None`   | Associated agent ID                                          |
| `team_id`     | `Optional[str]` | `None`   | Associated team ID                                           |
| `workflow_id` | `Optional[str]` | `None`   | Associated workflow ID                                       |
| `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](/reference/tracing/span) - Individual operations within a trace
* [DB Functions](/tracing/db-functions) - Query functions for traces and spans