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

# Platform client

> Read persisted traces and create or poll evaluation runs

This asynchronous HTTP client reads persisted evidence and starts or polls trace evaluations independently of trace export. It reuses an existing tracing client's resolved endpoint, API key, and project, with a separate lifecycle. Close it separately when you supply it to Reflect.

The SDK currently exposes trace reads and trace evaluation resources. The [HTTP API](https://docs.pandaprobe.com/reference/api/introduction.md) also documents operations such as sessions and monitors that are not typed SDK resources here.

All timeouts and polling intervals are **seconds**. Safe GETs have bounded retries; evaluation creation is sent once because the server has no idempotency-key contract. Poll the returned run ID. An uncertain create outcome must not be automatically retried.

`wait_visible` / `waitVisible` waits for a terminal persisted trace, including an error trace. Evaluation `wait` requires usable scores for every requested trace/metric pair; terminal status alone is insufficient. Missing, duplicate, nonnumeric, or failed evidence does not become a passing result.

## On this page

[Evaluations](#evaluations), [PlatformClient](#platformclient), [Traces](#traces).

## Example

This creates a real evaluation run for an existing trace. `trace_id` is a persisted task trace UUID from the same project.

```python theme={null}
from pandaprobe import Client
from pandaprobe.api import PlatformClient


async def evaluate(trace_id: str):
    client = Client()
    try:
        async with PlatformClient(client) as api:
            await api.traces.wait_visible(trace_id)
            run = await api.evaluations.create([trace_id], ["task_completion"])
            return await api.evaluations.wait(
                run.id, trace_ids=[trace_id], metrics=["task_completion"],
            )
    finally:
        client.shutdown()
```

## `Evaluations`

```python theme={null}
from pandaprobe.api.resources import Evaluations
```

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/api/resources.py#L78)

### Constructor

```text theme={null}
Evaluations(client: PlatformClient)
```

| Parameter | Type | Default / passing |
| - | - | - |
| `client` | `PlatformClient` | Required |

### Methods

> [accordion] metrics
>
> Returns the supported trace metric metadata from the platform.
>
> ```text theme={null}
> async metrics() -> list[Metric]
> ```

> [accordion] create
>
> Creates one batch trace-evaluation run. Deduplicates trace IDs and metric names and requires nonempty inputs. Creation is never automatically retried.
>
> ```text theme={null}
> async create(
>   trace_ids: list[str | UUID],
>   metrics: list[str],
>   *,
>   name: str | None=None,
>   model: str | None=None,
>   timeout: float | None=None,
> ) -> EvaluationRun
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `trace_ids` | `list[str \| UUID]` | Required |
> | `metrics` | `list[str]` | Required |
> | `name` | `str \| None` | `None`; keyword only |
> | `model` | `str \| None` | `None`; keyword only |
> | `timeout` | `float \| None` | `None`; keyword only |

> [accordion] get
>
> Fetches one evaluation run and verifies its identity. A RUNNING or PENDING result is not complete evidence.
>
> ```text theme={null}
> async get(run_id: str | UUID, *, timeout: float | None=None) -> EvaluationRun
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `run_id` | `str \| UUID` | Required |
> | `timeout` | `float \| None` | `None`; keyword only |

> [accordion] scores
>
> Fetches the score records for an evaluation run; use wait to require a complete usable set.
>
> ```text theme={null}
> async scores(run_id: str | UUID, *, timeout: float | None=None) -> list[Score]
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `run_id` | `str \| UUID` | Required |
> | `timeout` | `float \| None` | `None`; keyword only |

> [accordion] wait
>
> Poll one existing run; terminal status alone is not usable evidence.
>
> ```text theme={null}
> async wait(
>   run_id: str | UUID,
>   *,
>   trace_ids: list[str | UUID],
>   metrics: list[str],
>   timeout: float=120,
>   poll_interval: float=1.0,
> ) -> EvaluationResult
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `run_id` | `str \| UUID` | Required |
> | `trace_ids` | `list[str \| UUID]` | Required; keyword only |
> | `metrics` | `list[str]` | Required; keyword only |
> | `timeout` | `float` | `120`; keyword only |
> | `poll_interval` | `float` | `1.0`; keyword only |

## `PlatformClient`

```python theme={null}
from pandaprobe.api import PlatformClient
```

Use an existing SDK client's resolved identity, with an independent HTTP lifecycle.

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/api/client.py#L35)

### Constructor

```text theme={null}
PlatformClient(
  client: Client | None=None,
  *,
  config: SdkConfig | None=None,
  timeout: float=30.0,
  read_attempts: int=3,
  transport: httpx.AsyncBaseTransport | None=None,
)
```

| Parameter | Type | Default / passing |
| - | - | - |
| `client` | `Client \| None` | `None` |
| `config` | `SdkConfig \| None` | `None`; keyword only |
| `timeout` | `float` | `30.0`; keyword only |
| `read_attempts` | `int` | `3`; keyword only |
| `transport` | `httpx.AsyncBaseTransport \| None` | `None`; keyword only |

### Fields and properties

| Name | Type | Default / contract |
| - | - | - |
| `config` | `SdkConfig \| None` | Instance value; Instance attribute. |
| `timeout` | `float` | Instance value; Instance attribute. |
| `read_attempts` | `int` | Instance value; Instance attribute. |
| `traces` | `Not annotated` | Instance value; Instance attribute. |
| `evaluations` | `Not annotated` | Instance value; Instance attribute. |

### Methods

> [accordion] aclose
>
> ```text theme={null}
> async aclose() -> None
> ```

> [accordion] decode
>
> ```text theme={null}
> decode(model: type[T], value: Any, *, creation: bool=False) -> T
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `model` | `type[T]` | Required |
> | `value` | `Any` | Required |
> | `creation` | `bool` | `False`; keyword only |

> [accordion] decode\_many
>
> ```text theme={null}
> decode_many(model: type[T], value: Any) -> list[T]
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `model` | `type[T]` | Required |
> | `value` | `Any` | Required |

> [accordion] request
>
> ```text theme={null}
> async request(method: str, path: str, *, timeout: float | None=None, **kwargs: Any) -> Any
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `method` | `str` | Required |
> | `path` | `str` | Required |
> | `timeout` | `float \| None` | `None`; keyword only |
> | `kwargs` | `Any` | Additional arguments |

## `Traces`

```python theme={null}
from pandaprobe.api.resources import Traces
```

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/api/resources.py#L18)

### Constructor

```text theme={null}
Traces(client: PlatformClient)
```

| Parameter | Type | Default / passing |
| - | - | - |
| `client` | `PlatformClient` | Required |

### Methods

> [accordion] get
>
> Fetches one trace with span evidence and verifies that the returned trace ID matches the requested ID.
>
> ```text theme={null}
> async get(trace_id: str | UUID, *, timeout: float | None=None) -> Trace
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `trace_id` | `str \| UUID` | Required |
> | `timeout` | `float \| None` | `None`; keyword only |

> [accordion] list
>
> Returns a page of trace summaries. Limit must be 1–200 and offset must be nonnegative.
>
> ```text theme={null}
> async list(
>   *,
>   session_id: str | None=None,
>   status: str | None=None,
>   limit: int=50,
>   offset: int=0,
>   timeout: float | None=None,
> ) -> TracePage
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `session_id` | `str \| None` | `None`; keyword only |
> | `status` | `str \| None` | `None`; keyword only |
> | `limit` | `int` | `50`; keyword only |
> | `offset` | `int` | `0`; keyword only |
> | `timeout` | `float \| None` | `None`; keyword only |

> [accordion] iterate
>
> Iterates trace summaries in pages, stopping at the configured maximum or the end of the server result.
>
> ```text theme={null}
> async iterate(*, session_id: str | None=None, max_items: int=1000) -> AsyncIterator[TraceSummary]
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `session_id` | `str \| None` | `None`; keyword only |
> | `max_items` | `int` | `1000`; keyword only |

> [accordion] wait\_visible
>
> Wait for persisted, finished evidence, including task ERROR traces.
>
> ```text theme={null}
> async wait_visible(trace_id: str | UUID, *, timeout: float=30, poll_interval: float=0.5) -> Trace
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `trace_id` | `str \| UUID` | Required |
> | `timeout` | `float` | `30`; keyword only |
> | `poll_interval` | `float` | `0.5`; keyword only |

***

Signatures and fields are generated from the [SDK source](https://github.com/chirpz-ai/pandaprobe-sdk/tree/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python). See the [import index](https://docs.pandaprobe.com/reference/python/overview.md#public-import-index) for available entry points.


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