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

# Galtea Client

> Main entry point for the Galtea SDK

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

## Galtea

The `Galtea` class is the main entry point for the Galtea SDK. It provides access to all the functionalities of the SDK.

### Initialization

To initialize the `Galtea` class, you need to provide your API key obtained in the [settings page](https://platform.galtea.ai/settings) of the Galtea platform.

```python theme={"system"}
galtea = Galtea(api_key="YOUR_API_KEY")
```

To call Galtea through an API gateway, pass `base_url` and `headers`, or set `GALTEA_API_URL` and
`GALTEA_EXTRA_HEADERS`. See [Custom API URL and headers](https://docs.galtea.ai/v5.12/sdk/installation.md#custom-api-url-and-headers).

### Services

The `Galtea` class provides access to the following services:

* [`products`](https://docs.galtea.ai/v5.12/sdk/api/product/service): Access [product](https://docs.galtea.ai/v5.12/concepts/product.md) related functionalities.
* [`endpoint_connections`](https://docs.galtea.ai/v5.12/sdk/api/endpoint-connection/service): Access [endpoint connection](https://docs.galtea.ai/v5.12/concepts/product/endpoint-connection.md) related functionalities.
* [`phone_connections`](https://docs.galtea.ai/v5.12/sdk/api/phone-connection/service): Access [phone connection](https://docs.galtea.ai/v5.12/concepts/product/phone-connection.md) related functionalities.
* [`web_rtc_connections`](https://docs.galtea.ai/v5.12/sdk/api/webrtc-connection/service): Access [WebRTC connection](https://docs.galtea.ai/v5.12/concepts/product/webrtc-connection.md) related functionalities.
* [`storage`](https://docs.galtea.ai/v5.12/sdk/api/storage/service): Move files between this machine and the platform's object storage.
* [`versions`](https://docs.galtea.ai/v5.12/sdk/api/version/service): Access [version](https://docs.galtea.ai/v5.12/concepts/product/version.md) related functionalities.
* [`datasets`](https://docs.galtea.ai/v5.12/sdk/api/dataset/service): Access [dataset](https://docs.galtea.ai/v5.12/concepts/product/dataset.md) related functionalities.
* [`test_cases`](https://docs.galtea.ai/v5.12/sdk/api/test-case/service): Access [test cases](https://docs.galtea.ai/v5.12/concepts/product/dataset/test-case.md) related functionalities.
* [`metrics`](https://docs.galtea.ai/v5.12/sdk/api/metric/service): Access [metric](https://docs.galtea.ai/v5.12/concepts/metric.md) related functionalities.
* [`models`](https://docs.galtea.ai/v5.12/sdk/api/model/service): Access [model](https://docs.galtea.ai/v5.12/concepts/model.md) related functionalities.
* [`sessions`](https://docs.galtea.ai/v5.12/sdk/api/session/service): Access [session](https://docs.galtea.ai/v5.12/concepts/product/version/session.md) related functionalities.
* [`traces`](https://docs.galtea.ai/v5.12/sdk/api/trace/service): Access [trace](https://docs.galtea.ai/v5.12/concepts/product/version/session/trace.md) related functionalities.
* [`spans`](https://docs.galtea.ai/v5.12/sdk/api/span/service): Access [span](https://docs.galtea.ai/v5.12/concepts/product/version/session/span.md) collection and management.
* [`evaluations`](https://docs.galtea.ai/v5.12/sdk/api/evaluation/service): Access [evaluation](https://docs.galtea.ai/v5.12/concepts/product/version/session/evaluation.md) related functionalities.
* [`runs`](https://docs.galtea.ai/v5.12/sdk/api/run/service): Group the sessions and evaluations of one launch into a [run](https://docs.galtea.ai/v5.12/concepts/product/run.md).
* [`jobs`](https://docs.galtea.ai/v5.12/sdk/api/job/service): Inspect and cancel async jobs (e.g. inference batches started by `evaluations.run()`).
* [`simulator`](https://docs.galtea.ai/v5.12/sdk/api/simulator/service): Access [conversation simulator](https://docs.galtea.ai/v5.12/concepts/product/dataset/test-case/conversation-simulator.md) related functionalities.

### Example

```python theme={"system"}
products = galtea.products.list(limit=10)
```

### Errors

Every call reaches the platform over HTTP, so a failure arrives as a `requests` exception.

When the platform holds nothing under the id or name you passed, the SDK raises
`EntityNotFoundException`. It covers every service: `products.get`, `versions.get_by_name`,
`sessions.get_by_custom_id` and the rest all report a missing entity the same way.

Import it with `from galtea import EntityNotFoundException`.

```python theme={"system"}
try:
    metric = galtea.metrics.get_by_name(name=metric_name)
except EntityNotFoundException:
    metric = galtea.metrics.create(
        name=metric_name,
        evaluator_model_name="GPT-4.1",
        source="partial_prompt",
        judge_prompt="Determine whether the actual output is polite.",
        evaluation_params=["input", "actual_output"],
    )
```

`EntityNotFoundException` is the name to catch. It covers both ways the SDK learns that nothing
matched, so you never have to know which one happened.

For a version, you do not need this fallback. [`versions.get_or_create`](https://docs.galtea.ai/v5.12/sdk/api/version/get-or-create)
finds or creates the version in one call, and two jobs that run at the same time get the same one.

One lookup can also fail the opposite way. When a version name matches more than one version in the
product, [`versions.get_by_name`](https://docs.galtea.ai/v5.12/sdk/api/version/get-by-name) raises `AmbiguousVersionNameException`
instead of picking one. Import it with `from galtea import AmbiguousVersionNameException`. The
message lists each match, so you can call [`galtea.versions.get`](https://docs.galtea.ai/v5.12/sdk/api/version/get) with the ID
you want. No other service raises it.

> [!NOTE]
>
> Only a 404 that names an entity becomes `EntityNotFoundException`. A 404 for a path the API does
> not serve stays a plain `requests.HTTPError`, so a typo in a base URL never reads as a missing
> record. Every other status stays a plain `requests.HTTPError` too.

Read the status from `e.status_code`. It is always 404.

### When you need the response

The SDK learns that an entity is missing two ways, and raises a different class for each. Both are
`EntityNotFoundException`, so catching that name is enough unless you want the difference.

| Raised | When | Carries |
| - | - | - |
| `EntityNotFoundException` | a lookup by name found no match in a list the API returned in full | the message and `status_code` |
| `EntityNotFoundHTTPError` | the API answered 404 | those, plus `response` and `request` |

`EntityNotFoundHTTPError` also derives from `requests.HTTPError`, so a program that already catches
`requests.HTTPError` around a `get()` call keeps catching it. Nothing forces you to migrate.

The plain `EntityNotFoundException` is not a `requests.HTTPError`, because no request failed: the
API answered normally and the name was simply not in the result. Reach for `response` only after
catching `EntityNotFoundHTTPError`, where it is always present.


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