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

> List runs with optional filtering.

## Returns

Returns a list of [Run](https://docs.galtea.ai/concepts/product/run.md) objects.

## Example

```python theme={"system"}
runs = galtea.runs.list(
    product_ids=[product_id],
    sort_by_created_at="desc",
    limit=10,
)
```

## Parameters

**product\_ids** `string | list[string]`

The ID or IDs of the product(s) to filter runs by.

**version\_ids** `string | list[string]`

The ID or IDs of the version(s) to filter runs by.

**ids** `string | list[string]`

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

**custom\_ids** `string | list[string]`

The label or labels to filter runs by.

**statuses** `string | list[string]`

Filter runs by status. Valid values are `RUNNING`, `COMPLETED`, `FAILED` and `CANCELLED`. Other string
values are sent to the API unchanged, so values added in newer API versions can be used; the API
rejects invalid ones.

**from\_created\_at** `str | int`

Filter runs created at or after this timestamp. Accepts an ISO 8601 string (e.g. `'2024-01-01T00:00:00Z'`)
or a Unix timestamp in seconds.

**to\_created\_at** `str | int`

Filter runs created at or before this timestamp. Accepts an ISO 8601 string (e.g. `'2024-12-31T23:59:59Z'`)
or a Unix timestamp in seconds.

**sort\_by\_created\_at** `string`

Sort runs by creation date. Valid values are `"asc"` and `"desc"`.

**offset** `int`

Number of runs to skip before collecting results. Use it for pagination.

**limit** `int`

Maximum number of runs to return in a single request.

**search** `string`

Free text that matches either the label of a run (case-insensitive, anywhere in the label) or its
number. The number is accepted with or without a leading `#`, so both `42` and `#42` find run 42.

> [!NOTE]
>
> At least one of `product_ids`, `version_ids` or `ids` must be passed. The other filters narrow the
> result but do not satisfy this requirement on their own.


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