> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seekr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Observability

> Query and inspect spans to monitor agent runs

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](/flow/reference/query_spans_v1_observability_spans_post)

<CodeGroup>
  ```python Python theme={null}
  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']}")
  ```
</CodeGroup>

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](/flow/reference/retrieve_span_v1_observability_spans__span_id__get)

<CodeGroup>
  ```python Python theme={null}
  span = client.observability.retrieve_span(span_id="your_span_id")
  print(span)
  ```
</CodeGroup>

## Investigate a failed run

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```
</CodeGroup>