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

# Accessing your Traces

> Database convenience functions for querying traces and spans

Agno provides convenience functions on your database instance to query traces and spans. These functions work with any supported database (SQLite, PostgreSQL, etc.).

## 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 reference for [Trace](/reference/tracing/trace) for more information.

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

**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 reference for [Span](/reference/tracing/span) for more information.

### `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            | Description              |
| ---------------- | --------------- | ------------------------ |
| `trace_id`       | `Optional[str]` | Filter by trace ID       |
| `parent_span_id` | `Optional[str]` | Filter by parent span ID |

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

<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