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

# EU Data Residency

> Keep your speech sessions in the European Union with eu.api.gradium.ai

Gradium runs inference in both the EU and the US. By default you call a single
endpoint, `api.gradium.ai`, and requests are routed to the nearest cluster.
For European customers this already means that, in practice, sessions are
processed in the EU.

EU data residency is for when "in practice" is not enough. Once enabled on
your plan, EU processing becomes a guarantee that is enforced on every
request: your sessions are never re-routed outside the EU, and every response
tells you so.

## Endpoints

| Endpoint            | Behaviour                                                                                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.gradium.ai`    | Default. Routed to the nearest cluster; no residency commitment.                                                                                |
| `eu.api.gradium.ai` | EU-pinned. Same API, same keys, same paths. For organizations enrolled in EU data residency, sessions are guaranteed to be processed in the EU. |

The base URLs for the EU endpoint are:

```
https://eu.api.gradium.ai/api
wss://eu.api.gradium.ai/api
```

Everything else is unchanged: the same API key, the same routes, the same
request and response formats.

## What is guaranteed

For an organization enrolled in EU data residency:

* **Inference stays in the EU.** Text-to-Speech, Speech-to-Text and
  Speech-to-Speech sessions, over WebSocket or the one-shot REST endpoints,
  run on our EU clusters, located in Germany and France.
* **No cross-region fallback.** Under load a session may be served by another
  EU cluster, but never by a cluster outside the EU.
* **Fail closed.** If a pinned request ever reaches a non-EU cluster, it is
  refused rather than processed out of region (see
  [Rejections](#rejections)).
* **Session data is written in region.** Whatever session data we retain
  (see [Zero Data Retention](/guides/faq#how-do-i-enable-zero-data-retention)
  to retain none) is written by the cluster that served the session.

Account data, custom voices and pronunciation dictionaries are managed by our
control plane, which is hosted in the EU for all customers.

## How to opt in

<Note>
  EU data residency is available on our paid plans. It is enabled on your
  plan by our team; there is no self-serve toggle yet.
</Note>

### 1. Ask us to enable it

Contact [support@gradium.ai](mailto:support@gradium.ai) with your organization
name and pick one of two modes:

* **Explicit** (default): sessions are pinned to the EU when you call
  `eu.api.gradium.ai`. Calls to `api.gradium.ai` keep today's behaviour.
  Choose this if only part of your traffic needs the guarantee.
* **Implicit**: your whole organization is pinned to the EU, whichever
  endpoint you call. Choose this if all of your usage is in scope.

### 2. Point your integration at the EU endpoint

<CodeGroup>
  ```python Python SDK theme={null}
  import gradium

  client = gradium.client.GradiumClient(
      api_key="your-api-key",
      base_url="https://eu.api.gradium.ai/api",
  )
  ```

  ```bash cURL theme={null}
  # -D - prints the response headers, including x-gradium-residency
  curl -L -D - -o bonjour.wav -X POST https://eu.api.gradium.ai/api/post/speech/tts \
    -H "x-api-key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{"text": "Bonjour !", "voice_id": "YTpq7expH9539ERJ", "output_format": "wav", "only_audio": true}'
  ```

  ```text WebSocket theme={null}
  wss://eu.api.gradium.ai/api/speech/tts
  wss://eu.api.gradium.ai/api/speech/asr
  ```
</CodeGroup>

With **implicit** mode this step is optional, since every endpoint pins your
sessions to the EU, but we still recommend it.

### 3. Verify

Every response reports the residency the request actually got, so you can
check it instead of trusting a hostname:

* **REST**: the `x-gradium-residency` response header.
* **WebSocket**: the `residency` field of the `ready` message.

| Value                  | Meaning                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| `pinned; zone=eu`      | The guarantee is in force: this session is processed in the EU and will not leave it.       |
| `best-effort; zone=eu` | The request landed in the EU, but your organization is not enrolled: no commitment is made. |
| `none`                 | No region is involved: default endpoint, organization not enrolled.                         |

```json TTS ready theme={null}
{
  "type": "ready",
  "request_id": "req_...",
  "model_name": "default",
  "residency": "pinned; zone=eu",
  "sample_rate": 48000,
  "frame_size": 3840
}
```

<Tip>
  If you rely on the guarantee, assert `pinned` in your client and treat
  anything else as a configuration error. `best-effort` on `eu.api.gradium.ai`
  means residency has not been enabled on your plan yet.
</Tip>

## Rejections

A pinned request that reaches a cluster outside the EU is refused instead of
being processed out of region:

* **REST**: `403 Forbidden`
* **WebSocket**: close code `1008` (policy violation)

Both carry the reason
`This request must be sent to the eu region endpoint.` In practice this
happens when an organization in **implicit** mode calls an endpoint that is
not EU-pinned; the fix is to use `eu.api.gradium.ai`.

## Residency and Zero Data Retention

The two are independent and combine:

* **Data residency** governs *where* your requests are processed.
* **Zero Data Retention** governs *whether* request and response payloads are
  retained at all. See the
  [FAQ](/guides/faq#how-do-i-enable-zero-data-retention) to enable it.

For a Data Processing Agreement or details on our privacy and security
posture, contact [support@gradium.ai](mailto:support@gradium.ai).