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

# Stop an instance

> Pause an instance while keeping its files. A stopped instance bills disk only.

<RequestExample>
  ```bash curl wrap theme={null}
  curl -X POST \
    https://api.agent37.com/v1/instances/ab12cd34ef/stop \
    -H "Authorization: Bearer sk_live_..."
  ```

  ```python Python wrap theme={null}
  import requests

  response = requests.post(
      "https://api.agent37.com/v1/instances/ab12cd34ef/stop",
      headers={
          "Authorization": "Bearer sk_live_..."
      },
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript Node wrap theme={null}
  const response = await fetch(
    "https://api.agent37.com/v1/instances/ab12cd34ef/stop",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer sk_live_..."
      },
    },
  );
  if (!response.ok) {
    throw new Error(await response.text());
  }
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 wrap theme={null}
  {
    "id": "ab12cd34ef",
    "status": "stopped"
  }
  ```
</ResponseExample>

Authenticate with `Authorization: Bearer sk_live_...` on `https://api.agent37.com`.

## Path parameters

<ParamField path="id" type="string" required>
  The instance id, returned when you create an instance.
</ParamField>

## Behavior and errors

`POST /v1/instances/{id}/stop` halts the container. The agent stops doing work (no cron, no heartbeats, no responses) and `status` becomes `stopped`. The data stays intact, CPU and memory are released back to the host, and the disk stays reserved on that host.

Stop also works on a `sleeping` instance, and the difference is intent: a sleeper wakes on any request, a stopped instance stays down until an explicit `start`. Stopping a sleeper discards its checkpoint (the data stays) and its URLs stop waking it. There are two exceptions. While the sleep checkpoint is being written, stop returns `409 try_again`; the window is tens of seconds on a large instance, so retry with backoff. A sleeper that has been moved to cold storage after a long idle stretch cannot be stopped: stop returns `400 invalid_request` saying the instance is parked in cold storage. Wake it first, with [`start`](/docs/agents-api/instances/start) or any request to its URL, or delete it.

Stopping an already stopped instance returns the same ack again; any other state returns `400`.

See [Instance lifecycle](/docs/agents-api/instance-lifecycle) for disk persistence and boot hooks. Retrieve the [instance object](/docs/agents-api/instances/get) for its full representation.


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