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

# Client

> Initialize tracing, submit traces and scores, and manage export lifecycle

The tracing client owns configuration and a background export queue. Use an explicit client when an application needs separate identities; use the module-level helpers for the global client. Initialization does not activate Reflect.

Client construction resolves credentials from arguments and environment variables. Missing API key or project name raises when tracing is enabled. The global getter attempts environment initialization once and returns no client if it cannot initialize. Reinitializing the global client shuts down its predecessor.

`score` submits a programmatic score; it does not start a platform evaluation. Scores use a string value, including numeric values such as `"0.95"`. Export completion is separate from platform persistence and evaluation completion.

See [tracing quickstart](https://docs.pandaprobe.com/tracing/get-started/quickstart.md) for provider/framework setup.

`flush()` and `shutdown()` block; call them outside latency-sensitive async work or offload them when necessary. `Client` does not install itself as the global client; `init()` does.

## On this page

[Client](#client), [**version**](#__version__), [flush](#flush), [get\_client](#get_client), [init](#init), [score](#score), [shutdown](#shutdown).

## Example

```python theme={null}
from pandaprobe import Client

client = Client()  # Resolves PANDAPROBE_* credentials.
try:
    with client.trace("support", input={"messages": [{"role": "user", "content": "Hello"}]}) as trace:
        trace.set_output({"messages": [{"role": "assistant", "content": "How can I help?"}]})
    client.score(trace.trace_id, "review", "1", reason="Reviewed by the application")
finally:
    client.shutdown()
```

## `Client`

```python theme={null}
from pandaprobe import Client
```

PandaProbe SDK client.

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

### Constructor

```text theme={null}
Client(
  *,
  api_key: str | None=None,
  project_name: str | None=None,
  endpoint: str | None=None,
  environment: str | None=None,
  release: str | None=None,
  enabled: bool | None=None,
  batch_size: int | None=None,
  flush_interval: float | None=None,
  max_queue_size: int | None=None,
  debug: bool | None=None,
)
```

| Parameter | Type | Default / passing |
| - | - | - |
| `api_key` | `str \| None` | `None`; keyword only |
| `project_name` | `str \| None` | `None`; keyword only |
| `endpoint` | `str \| None` | `None`; keyword only |
| `environment` | `str \| None` | `None`; keyword only |
| `release` | `str \| None` | `None`; keyword only |
| `enabled` | `bool \| None` | `None`; keyword only |
| `batch_size` | `int \| None` | `None`; keyword only |
| `flush_interval` | `float \| None` | `None`; keyword only |
| `max_queue_size` | `int \| None` | `None`; keyword only |
| `debug` | `bool \| None` | `None`; keyword only |

### Fields and properties

| Name | Type | Default / contract |
| - | - | - |
| `enabled` | `bool` | Instance value; read-only; Read-only property. |
| `config` | `SdkConfig` | Instance value; read-only; Read-only property. |

### Methods

> [accordion] capture\_traces
>
> Capture IDs submitted by existing instrumentation in an explicit scope.
>
> ```text theme={null}
> capture_traces(
>   *,
>   metadata: dict[str, Any] | None=None,
>   session_id: str | None=None,
>   max_traces: int=1000,
>   on_submit: Callable[[dict[str, Any]], None] | None=None,
> ) -> TraceCapture
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `metadata` | `dict[str, Any] \| None` | `None`; keyword only |
> | `session_id` | `str \| None` | `None`; keyword only |
> | `max_traces` | `int` | `1000`; keyword only |
> | `on_submit` | `Callable[[dict[str, Any]], None] \| None` | `None`; keyword only |

> [accordion] trace
>
> Start a new trace and return a `TraceContext` context manager.
>
> ```text theme={null}
> trace(
>   name: str,
>   *,
>   input: Any=None,
>   session_id: str | None=None,
>   user_id: str | None=None,
>   tags: list[str] | None=None,
>   metadata: dict[str, Any] | None=None,
>   **kwargs: Any,
> )
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `name` | `str` | Required |
> | `input` | `Any` | `None`; keyword only |
> | `session_id` | `str \| None` | `None`; keyword only |
> | `user_id` | `str \| None` | `None`; keyword only |
> | `tags` | `list[str] \| None` | `None`; keyword only |
> | `metadata` | `dict[str, Any] \| None` | `None`; keyword only |
> | `kwargs` | `Any` | Additional arguments |

> [accordion] log\_trace
>
> Queues a prebuilt trace record for export. This is asynchronous ingestion, not confirmation that the trace is persisted.
>
> ```text theme={null}
> log_trace(trace_data: TraceData) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `trace_data` | `TraceData` | Required |

> [accordion] score
>
> Submit a programmatic score for a trace.
>
> ```text theme={null}
> score(
>   trace_id: str | UUID,
>   name: str,
>   value: str,
>   *,
>   data_type: str='NUMERIC',
>   reason: str | None=None,
>   metadata: dict[str, Any] | None=None,
> ) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `trace_id` | `str \| UUID` | Required |
> | `name` | `str` | Required |
> | `value` | `str` | Required |
> | `data_type` | `str` | `'NUMERIC'`; keyword only |
> | `reason` | `str \| None` | `None`; keyword only |
> | `metadata` | `dict[str, Any] \| None` | `None`; keyword only |

> [accordion] flush
>
> Block until all queued items are sent.
>
> ```text theme={null}
> flush(timeout: float=30.0) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `timeout` | `float` | `30.0` |

> [accordion] shutdown
>
> Flush remaining items and release resources.
>
> ```text theme={null}
> shutdown() -> None
> ```

> [accordion] on\_error
>
> Registers a callback for export transport errors. Errors inside the callback are caught by the SDK.
>
> ```text theme={null}
> on_error(callback: Callable[[Exception], None]) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `callback` | `Callable[[Exception], None]` | Required |

## `__version__`

```python theme={null}
from pandaprobe import __version__
```

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

```text theme={null}
__version__ = '0.6.0'
```

## `flush`

```python theme={null}
from pandaprobe import flush
```

Block until all queued items are sent (delegates to the global client).

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

```text theme={null}
flush(timeout: float=30.0) -> None
```

| Parameter | Type | Default / passing |
| - | - | - |
| `timeout` | `float` | `30.0` |

## `get_client`

```python theme={null}
from pandaprobe import get_client
```

Return the current global client.

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

```text theme={null}
get_client() -> Client | None
```

## `init`

```python theme={null}
from pandaprobe import init
```

Configure and set the global PandaProbe client singleton.

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

```text theme={null}
init(
  *,
  api_key: str | None=None,
  project_name: str | None=None,
  endpoint: str | None=None,
  environment: str | None=None,
  release: str | None=None,
  enabled: bool | None=None,
  batch_size: int | None=None,
  flush_interval: float | None=None,
  max_queue_size: int | None=None,
  debug: bool | None=None,
) -> Client
```

| Parameter | Type | Default / passing |
| - | - | - |
| `api_key` | `str \| None` | `None`; keyword only |
| `project_name` | `str \| None` | `None`; keyword only |
| `endpoint` | `str \| None` | `None`; keyword only |
| `environment` | `str \| None` | `None`; keyword only |
| `release` | `str \| None` | `None`; keyword only |
| `enabled` | `bool \| None` | `None`; keyword only |
| `batch_size` | `int \| None` | `None`; keyword only |
| `flush_interval` | `float \| None` | `None`; keyword only |
| `max_queue_size` | `int \| None` | `None`; keyword only |
| `debug` | `bool \| None` | `None`; keyword only |

## `score`

```python theme={null}
from pandaprobe import score
```

Submit a programmatic score for a trace (delegates to the global client).

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

```text theme={null}
score(
  trace_id: str | UUID,
  name: str,
  value: str,
  *,
  data_type: str='NUMERIC',
  reason: str | None=None,
  metadata: dict[str, Any] | None=None,
) -> None
```

| Parameter | Type | Default / passing |
| - | - | - |
| `trace_id` | `str \| UUID` | Required |
| `name` | `str` | Required |
| `value` | `str` | Required |
| `data_type` | `str` | `'NUMERIC'`; keyword only |
| `reason` | `str \| None` | `None`; keyword only |
| `metadata` | `dict[str, Any] \| None` | `None`; keyword only |

## `shutdown`

```python theme={null}
from pandaprobe import shutdown
```

Flush remaining items and release resources (delegates to the global client).

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

```text theme={null}
shutdown() -> None
```

***

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.