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

# List Spans

> Retrieve spans for a trace.

> [!WARNING]
>
> You are reading the docs of Galtea 5.13. [Read this page in the latest version](https://docs.galtea.ai/sdk/api/span/list.md).

## Returns

Returns a list of [Span](https://docs.galtea.ai/v5.13/concepts/product/version/session/span.md) objects.

## Example

```python theme={"system"}
spans = galtea.spans.list(trace_id=trace_id)
```

## Parameters

**trace\_id** `string | list[string]`

Filter spans by trace ID(s).

**session\_id** `string | list[string]`

Filter spans by session ID(s).

**types** `list[string | SpanType]`

Filter spans by type. Options: `SPAN`, `GENERATION`, `EVENT`, `AGENT`, `TOOL`, `CHAIN`, `RETRIEVER`, `EVALUATOR`, `EMBEDDING`, `GUARDRAIL`. Other string values are sent to the API unchanged, so values added in newer API versions can be used; the API rejects invalid ones.

**names** `list[string]`

Filter spans by name.

**from\_start\_time** `str | int` (default: None)

Filter spans started at or after this timestamp. Accepts ISO 8601 string (e.g., `'2024-01-01T00:00:00Z'`) or Unix timestamp in seconds. Can be used independently or together with `to_start_time`.

**to\_start\_time** `str | int` (default: None)

Filter spans started at or before this timestamp. Accepts ISO 8601 string (e.g., `'2024-12-31T23:59:59Z'`) or Unix timestamp in seconds. Can be used independently or together with `from_start_time`.

**sort\_by\_start\_time** `string`

Sort spans by start\_time. Valid values: `asc`, `desc`.

**offset** `int`

Number of spans to skip for pagination. Default: `0`.

**limit** `int`

Maximum number of spans to return. Default: `10000`.

**id** `string | list[string]` (default: None)

The ID or IDs of the span(s) to retrieve.

> [!NOTE]
>
> At least one of `trace_id`, `session_id`, or `id` must be provided.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.