> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/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](/reference/tracing/trace).

### `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](/reference/tracing/span).

### `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.
</Warning>

<Note>
  Unlike `get_traces()`, `get_spans()` returns a list without a count.
</Note>

## 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](/reference/tracing/trace) - Full `Trace` object definition
* [Span Reference](/reference/tracing/span) - Full `Span` object definition