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

# Connection pre-warming

A request that opens its connection on demand pays the full DNS lookup, TCP
handshake, and TLS handshake before the first audio byte can leave. For a
distant client that is a network round trip or more, and on a dictation of a
few seconds it is a noticeable share of the total wait.

The `GET /warm` endpoint takes that setup off the critical path. Call it as soon
as you know audio is coming, typically the moment the user reaches for the
record button, and the connection is established in the background while they
are still getting ready to speak. The transcription request then starts
uploading audio immediately.

## How `/warm` works

`GET /warm` is an unauthenticated no-op:

```bash theme={null}
curl https://dictation.assemblyai.com/warm
```

```json theme={null}
{ "warm": "toasty" }
```

No API key is required, and the response body carries no information. The value
of the call is the open connection it leaves in your HTTP client's pool.

<Tabs groupId="language">
  <Tab language="python-sdk" title="Python SDK" default>
    ```python theme={null}
    import assemblyai as aai

    aai.settings.api_key = "<YOUR_API_KEY>"

    with aai.DictationTranscriber() as transcriber:
        # Call as soon as you know audio is coming (e.g. the user taps record).
        transcriber.warm()

        # Same transcriber, so this reuses the warmed connection.
        result = transcriber.transcribe_live("clip.wav")
        print(result.text)
    ```

    `warm()` returns `True` once the connection is open and `False` if it could not
    be opened, and never raises. `AsyncDictationTranscriber.warm()` is the
    coroutine equivalent, which pairs well with
    `asyncio.create_task(transcriber.warm())` so the handshake overlaps whatever
    your app is doing next.
  </Tab>

  <Tab language="python" title="Python">
    ```python theme={null}
    import requests

    session = requests.Session()

    # Call as soon as you know audio is coming (e.g. the user taps record).
    session.get("https://dictation.assemblyai.com/warm", timeout=10)

    # Same session, so this reuses the warmed connection.
    with open("clip.wav", "rb") as f:
        response = session.post(
            "https://dictation.assemblyai.com/v1/transcribe/live",
            headers={"Authorization": "<YOUR_API_KEY>"},
            files={
                "config": (None, "{}", "application/json"),
                "audio": ("clip.wav", f, "audio/wav"),
            },
            timeout=90,
        )
    print(response.json()["text"])
    ```
  </Tab>

  <Tab language="javascript" title="JavaScript">
    ```javascript theme={null}
    import { readFileSync } from "fs";

    // Call as soon as you know audio is coming (e.g. the user taps record).
    // Node's fetch keeps the connection alive in its pool by default.
    await fetch("https://dictation.assemblyai.com/warm");

    // Same process, so this reuses the warmed connection.
    const audio = readFileSync("clip.wav");
    const form = new FormData();
    form.append("config", new Blob(["{}"], { type: "application/json" }));
    form.append("audio", new Blob([audio], { type: "audio/wav" }), "clip.wav");

    const response = await fetch(
      "https://dictation.assemblyai.com/v1/transcribe/live",
      { method: "POST", headers: { Authorization: "<YOUR_API_KEY>" }, body: form }
    );
    console.log((await response.json()).text);
    ```
  </Tab>
</Tabs>

## When to call it

A warmed connection only helps if it is still in the pool when the transcription
request goes out, and if that request travels through the same HTTP client and
the same host.

* **Same client.** The warm call and the transcription must share a connection
  pool. A fresh `requests.Session`, `httpx.Client`, or `AssemblyAI` instance for
  the transcription gets a fresh connection and pays the handshake anyway.
* **Same host.** Pre-warming is per host, so a connection warmed against
  `dictation.assemblyai.com` is no use to a request aimed at
  `dictation.eu.assemblyai.com`. Warm the host you are about to call. See
  [Cloud endpoints & data residency](/docs/dictation/endpoints-and-data-zones).
* **Not too early.** Idle connections are evicted after a short window. In the
  Python SDK that window is `settings.keepalive_expiry`, which inherits httpx's
  5-second default unless you raise it. Warm shortly before the request rather
  than at application startup, or raise `keepalive_expiry` so one call covers a
  longer pause.

If the connection has been evicted or closed by the time you transcribe, the
request silently opens a fresh one and pays the full handshake. The warm-up
bought nothing, but nothing breaks either.

The ideal moment is when you know audio is coming but do not have it yet. In a
dictation app that is the moment the user starts recording: the handshake then
runs concurrently with the recording, and by the time they stop speaking the
connection is open and fresh. `/warm` is idempotent and cheap, so calling it
again to refresh an aging connection is fine.