Observability

Observability spans are records generated during agent runs that capture timing, model usage, token consumption, and error details. Use the observability resource to query spans across runs or retrieve the full record for a specific span.

Query spans

Use query_spans to retrieve span summaries matching a set of filters. All filters are optional. If min_start_time is not provided, the query defaults to the last 15 minutes. Start with run_id to scope results to a specific run.

Endpoint: POST /v1/observability/spans Query spans

from seekrai import SeekrFlow

client = SeekrFlow(api_key="your_api_key")

spans = client.observability.query_spans(
    run_id="your_run_id"
)

for span in spans.spans:
    print(f"Span ID: {span['span_id']}, Name: {span['span_name']}, Kind: {span['kind']}")

Additional filters you can combine:

Parameter	Description
`agent_id`	Filter by agent
`thread_id`	Filter by thread
`trace_id`	Filter by trace
`group`	Filter by group
`metadata`	Filter by custom metadata key-value pairs
`min_start_time`	Filter spans starting after this datetime. Defaults to 15 minutes before the request time if not provided.
`max_start_time`	Filter spans starting before this datetime
`limit`	Number of results to return (default: 100)
`offset`	Pagination offset (default: 0)
`order`	Sort order by start time (`asc` or `desc`, default: `desc`)

Retrieve a span

Use retrieve_span to fetch the full span object for a specific span by ID. Unlike query_spans, which returns summaries, this returns the complete record.

Endpoint: GET /v1/observability/spans/{span_id} Retrieve span

span = client.observability.retrieve_span(span_id="your_span_id")
print(span)

Investigate a failed run

A common pattern is to query spans for a run, then retrieve a specific span to investigate further.

from seekrai import SeekrFlow

client = SeekrFlow(api_key="your_api_key")

# Get all spans for a run
spans = client.observability.query_spans(run_id="your_run_id")

# Find the first span with an exception
failed_span = next(
    (s for s in spans.spans if s.get("is_exception")), None
)

if failed_span:
    full_span = client.observability.retrieve_span(span_id=failed_span["span_id"])
    print(full_span)