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.

# 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 for more information.

db.get_traces()

Get multiple traces with filtering and pagination.

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

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 for more information.

db.get_spans()

Get multiple spans for a trace or parent.

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

Unlike get_traces(), get_spans() returns a list without a count.

Example: Analyzing a Run

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 - Full Trace object definition
• Span Reference - Full Span object definition