# Regions

Choose where in the world a sandbox runs.

A region is a part of the world: `eu` (servers in the European Economic Area or the United Kingdom), `us` and `apac`. A sandbox runs in one region, and stays there: it is never placed, moved or kept in another. Only regions that have servers now are offered.

`GET /v1/regions`

```shell
curl -X GET https://agental.io/v1/regions \
  -H "Authorization: Bearer $AGENTAL_API_KEY"
```

```json
{
  "regions": [
    {
      "name": "eu",
      "label": "Europe",
      "about": "Servers in the European Economic Area or the United Kingdom.",
      "default": true,
      "sizesWithRoom": ["tiny", "small", "medium", "large"]
    }
  ]
}
```

- `default` is where a sandbox is made when its create names no region. That is `eu`.
- `sizesWithRoom` is what could be made there now. It changes by the second.

## Make a sandbox in a region

```shell
curl -X POST https://agental.io/v1/sandboxes \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Idempotency-Key: task-44" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent-1","regions":["eu","us"]}'
```

- `region` names one region. `regions` names up to three, in the order to try them: the sandbox is made in the first that has room. Send one or the other.
- Left out, the sandbox is made in `eu`. `main` means `eu` too.
- A sandbox made from a snapshot is made in the snapshot's region.
- A region with no servers answers `400 unsupported_region`, and the message names the regions there are.

## When a region is full

When no server in the region has room right now, a create waits for some before it is refused. It answers `202` with `waiting`, and nothing is made yet: send the same request again with the same `Idempotency-Key` every 10 seconds, as the SDKs do, and it is made as soon as there is room. It is waited for until `waiting.until`, kept from its first try, about two and a half minutes. A create is never moved to another region by itself. When none of the regions it names has room by then, it answers `409 capacity_exceeded`, and `error.regionsWithRoom` lists the other regions that have room for its size now. Send it again to one of them with a new `Idempotency-Key`, or wait and try again.

```json
{
  "waiting": {
    "region": "eu",
    "askedAt": "2026-11-05T12:00:00.000Z",
    "until": "2026-11-05T12:02:30.000Z"
  }
}
```

Above, what a create that waits for room answers. Below, what one answers when its wait is over and there is still none.

```json
{
  "error": {
    "code": "capacity_exceeded",
    "message": "Every server in region eu is too busy to take another sandbox right now. Try again later. Region us has room for one now: send region us, with a new Idempotency-Key.",
    "regionsWithRoom": ["us"]
  }
}
```

---

Every page of these docs as Markdown: [llms.txt](https://agental.io/llms.txt)