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

# Regions

> Understanding PolarGrid edge regions

# Regions

PolarGrid runs GPU infrastructure at edge locations to minimize latency.

## Available Regions

| ID       | Name          | Location       | Country |
| -------- | ------------- | -------------- | ------- |
| `yto-01` | Toronto       | Canada Central | CA      |
| `yul-01` | Montreal      | Canada East    | CA      |
| `yul-02` | Montreal 02   | Canada East    | CA      |
| `yvr-02` | Vancouver     | Canada West    | CA      |
| `nyc-01` | New York      | US East        | US      |
| `nyc-02` | New York 02   | US East        | US      |
| `dfw-01` | Dallas        | US Central     | US      |
| `dfw-02` | Dallas 02     | US Central     | US      |
| `sfo-01` | San Francisco | US West        | US      |
| `lax-01` | Los Angeles   | US West        | US      |
| `sea-01` | Seattle       | US West        | US      |
| `chi-01` | Chicago       | US Central     | US      |
| `phx-01` | Phoenix       | US West        | US      |
| `was-01` | Washington DC | US East        | US      |
| `mia-01` | Miami         | US East        | US      |
| `sfo-03` | San Francisco | US West        | US      |

## Endpoint URLs

```
https://api.{region-id}.edge.polargrid.ai
```

Examples:

* `https://api.yto-01.edge.polargrid.ai`
* `https://api.yul-01.edge.polargrid.ai`
* `https://api.yvr-02.edge.polargrid.ai`
* `https://api.nyc-01.edge.polargrid.ai`
* `https://api.dfw-01.edge.polargrid.ai`
* `https://api.sfo-01.edge.polargrid.ai`
* `https://api.lax-01.edge.polargrid.ai`
* `https://api.sea-01.edge.polargrid.ai`
* `https://api.chi-01.edge.polargrid.ai`
* `https://api.phx-01.edge.polargrid.ai`
* `https://api.was-01.edge.polargrid.ai`
* `https://api.mia-01.edge.polargrid.ai`
* `https://api.sfo-03.edge.polargrid.ai`

## Auto-Routing

The SDKs can automatically select the fastest region:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Calls the autorouter which returns the optimal edge based on your origin
  const client = await PolarGrid.create({
    apiKey: "pg_your_api_key",
    debug: true, // See selected region
  });

  // [PolarGrid] Auto-routing: selected Toronto (yto-01)

  console.log(client.getRegionId()); // 'yto-01'
  console.log(client.getRegionName()); // 'Toronto'
  ```

  ```python Python theme={null}
  # Calls the autorouter which returns the optimal edge based on your origin
  client = await PolarGrid.create(api_key="pg_your_api_key", debug=True)

  # [PolarGrid] Auto-routing: selected Toronto (yto-01)

  print(client.get_region_id())   # 'yto-01'
  print(client.get_region_name()) # 'Toronto'
  ```
</CodeGroup>

## Explicit Region Selection

You can specify a region by ID or alias:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // By alias (case-insensitive)
  const client = new PolarGrid({
    apiKey: "pg_...",
    region: "toronto", // or 'vancouver', 'montreal'
  });

  // By ID
  const client = new PolarGrid({
    apiKey: "pg_...",
    region: "yto-01", // or 'yvr-02', 'yul-01'
  });
  ```

  ```python Python theme={null}
  # By alias
  client = PolarGrid(api_key="pg_...", region="toronto")

  # By ID
  client = PolarGrid(api_key="pg_...", region="yto-01")
  ```
</CodeGroup>

## Region Aliases

For convenience, these aliases are supported:

| Alias                                        | Region ID |
| -------------------------------------------- | --------- |
| `toronto`, `yto`                             | `yto-01`  |
| `montreal`, `yul`                            | `yul-01`  |
| `vancouver`, `yvr`                           | `yvr-02`  |
| `new-york`, `newyork`, `nyc`                 | `nyc-01`  |
| `dallas`, `dfw`                              | `dfw-01`  |
| `san-francisco`, `sanfrancisco`, `sf`, `sfo` | `sfo-01`  |

The `-02` variants (e.g. `yul-02`, `nyc-02`, `dfw-02`) and `lax-01`, `sea-01`, `chi-01`, `phx-01`, `was-01`, `mia-01`, `sfo-03` are reachable only by explicit region ID — they have no alias.

## Checking Latency

### CLI

```bash theme={null}
# List regions with current latency
polargrid regions list

# Detailed ping test
polargrid regions ping --count 5
```

### SDK

Auto-routing logs latency when debug is enabled:

```javascript theme={null}
const client = await PolarGrid.create({
  apiKey: "pg_...",
  debug: true,
});
// [PolarGrid] Auto-routing: selected Toronto (yto-01)
```

## Default Region

If you don't specify a region and don't use auto-routing, the SDKs default to **Toronto** (`yto-01`).

For CLI, you can set a default:

```bash theme={null}
polargrid config set default_region yvr-02
```

## Health Checks and Fallback

### Checking Region Health

Each edge node exposes a `/health` endpoint:

```bash theme={null}
curl https://api.yto-01.edge.polargrid.ai/health
```

A healthy response includes the node ID, runtime info, and loaded models. Use this to verify a region is operational before pinning traffic to it.

### Autorouter Discovery

The autorouter returns the single best edge for the caller. It detects the
caller's country (from request geo) and returns the **nearest edge in that
country** — a US caller is routed to the nearest US edge, a Canadian caller to
the nearest Canadian edge — even when an edge across the border is physically
closer. If no healthy edge exists in the caller's country, it falls back to the
globally nearest edge.

```bash theme={null}
curl https://autorouter.polargrid.ai/v1/route
# → {"region":"yto-01","name":"Toronto Edge","endpoint":"https://api.yto-01.edge.polargrid.ai:443","ttl":3600}
```

The `endpoint` field is the base URL you POST inference to. The `ttl` (seconds) is a hint for how long the SDK should cache the choice before re-asking.

### Fallback Strategy

If you're pinning to a specific region (not using auto-routing), we recommend this fallback pattern:

1. **Primary**: Your chosen region (e.g., `yto-01`)
2. **Fallback**: Try the next-closest region if the primary returns 5xx or times out
3. **Auto-route**: Fall back to `PolarGrid.create()` which calls the autorouter

```javascript theme={null}
async function createWithFallback(apiKey, preferredRegion, fallbackRegion) {
  try {
    const client = new PolarGrid({ apiKey, region: preferredRegion });
    await client.listModels(); // verify it's reachable
    return client;
  } catch {
    console.warn(`${preferredRegion} unreachable, trying ${fallbackRegion}`);
    try {
      const fallback = new PolarGrid({ apiKey, region: fallbackRegion });
      await fallback.listModels(); // verify fallback is reachable too
      return fallback;
    } catch {
      console.warn('Fallback failed, using auto-routing');
      return PolarGrid.create({ apiKey });
    }
  }
}
```

<Tip>
  For most use cases, `PolarGrid.create()` is the best option — it handles region selection and failover automatically. Only pin to a specific region if you need deterministic routing for compliance or latency guarantees.
</Tip>

## Direct API Access

For raw HTTP requests, use the full endpoint:

```bash theme={null}
curl https://api.yto-01.edge.polargrid.ai/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-3.5-27b", "messages": [...]}'
```