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
yto-02	Toronto 02	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
dal-01	Dallas	US Central	US
dal-02	Dallas 02	US Central	US
sfo-01	San Francisco	US West	US

Endpoint URLs

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

Examples:

• https://api.yto-01.edge.polargrid.ai
• https://api.yto-02.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.dal-01.edge.polargrid.ai
• https://api.sfo-01.edge.polargrid.ai

Auto-Routing

The SDKs can automatically select the fastest region:

JavaScript

// 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'

Explicit Region Selection

You can specify a region by ID or alias:

JavaScript

// 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'
});

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, dal	dal-01
san-francisco, sanfrancisco, sf, sfo	sfo-01

The -02 variants (e.g. yto-02, yul-02, nyc-02, dal-02) are reachable only by explicit region ID.

Checking Latency

CLI

# 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:

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:

polargrid config set default_region yvr-02

Health Checks and Fallback

Checking Region Health

Each edge node exposes a /health endpoint:

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.

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

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 });
    }
  }
}

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.

Direct API Access

For raw HTTP requests, use the full endpoint:

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": [...]}'