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

# Accessing your Traces

> Database convenience functions for querying traces and spans

Agno provides convenience functions on your database instance to query traces and spans. Parameter support can vary by database implementation.

## Trace Functions

### `db.get_trace()`

Get a single trace by identifier.

```python theme={null}
# Get by trace_id
trace = db.get_trace(trace_id="abc123...")

# Get by run_id (returns most recent match)
trace = db.get_trace(run_id=response.run_id)
```

**Parameters:**

| Parameter | Type | Description |
| - | - | - |
| `trace_id` | `Optional[str]` | Unique trace identifier |
| `run_id` | `Optional[str]` | Filter by run ID |

**Returns:** `Trace` or `None`

See the [Trace reference](https://agno-v2.mintlify.site/reference/tracing/trace.md).

### `db.get_traces()`

Get multiple traces with filtering and pagination.

```python theme={null}
# Get recent traces
traces, total_count = db.get_traces(limit=20)

# Filter by agent
traces, count = db.get_traces(agent_id=agent.id)

# Filter by time range
from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)
traces, count = db.get_traces(
    start_time=now - timedelta(hours=1),
    end_time=now,
    limit=100
)
```

**Parameters:**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `run_id` | `Optional[str]` | `None` | Filter by run ID |
| `session_id` | `Optional[str]` | `None` | Filter by session ID |
| `user_id` | `Optional[str]` | `None` | Filter by user ID |
| `agent_id` | `Optional[str]` | `None` | Filter by agent ID |
| `team_id` | `Optional[str]` | `None` | Filter by team ID |
| `workflow_id` | `Optional[str]` | `None` | Filter by workflow ID |
| `status` | `Optional[str]` | `None` | Filter by status (`OK`, `ERROR`, `UNSET`) |
| `start_time` | `Optional[datetime]` | `None` | Filter traces after this time |
| `end_time` | `Optional[datetime]` | `None` | Filter traces before this time |
| `limit` | `Optional[int]` | `20` | Max traces to return |
| `page` | `Optional[int]` | `1` | Page number for pagination |
| `filter_expr` | `Optional[Dict[str, Any]]` | `None` | Advanced filter expression dict, built with `agno.filters` (e.g. `EQ("status", "OK").to_dict()`). Supports AND/OR/NOT logic and operators like EQ, NEQ, GT, GTE, LT, LTE, IN, CONTAINS, STARTSWITH |

**Returns:** `tuple[List[Trace], int]` - (traces, total\_count)

## Span Functions

### `db.get_span()`

Get a single span by ID.

```python theme={null}
span = db.get_span(span_id="xyz789...")
if span:
    print(f"{span.name}: {span.duration_ms}ms")
```

**Parameters:**

| Parameter | Type | Description |
| - | - | - |
| `span_id` | `str` | Unique span identifier |

**Returns:** `Span` or `None`

See the [Span reference](https://agno-v2.mintlify.site/reference/tracing/span.md).

### `db.get_spans()`

Get multiple spans for a trace or parent.

```python theme={null}
# Get all spans in a trace
spans = db.get_spans(trace_id=trace.trace_id)

# Get child spans of a specific parent
children = db.get_spans(parent_span_id=root_span.span_id)
```

**Parameters:**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `trace_id` | `Optional[str]` | `None` | Filter by trace ID |
| `parent_span_id` | `Optional[str]` | `None` | Filter by parent span ID |
| `limit` | `Optional[int]` | `1000` | Max spans to return |

**Returns:** `List[Span]`

> [!WARNING]
>
> In Agno v2.7.2, synchronous `SqliteDb.get_spans()` does not accept `limit`. Omit `limit` when using SQLite. The other filters and the SQLite example below work as shown.

> [!NOTE]
>
> Unlike `get_traces()`, `get_spans()` returns a list without a count.

## Example: Analyzing a Run

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

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

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

if trace:
    print(f"Trace: {trace.name} ({trace.duration_ms}ms)")

    # Get all spans
    spans = db.get_spans(trace_id=trace.trace_id)

    # Print execution tree
    for span in sorted(spans, key=lambda s: s.start_time):
        indent = "  " if span.parent_span_id else ""
        print(f"{indent}- {span.name} ({span.duration_ms}ms)")
```

## See Also

* [Trace Reference](https://agno-v2.mintlify.site/reference/tracing/trace.md) - Full `Trace` object definition
* [Span Reference](https://agno-v2.mintlify.site/reference/tracing/span.md) - Full `Span` object definition


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