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:

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, 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

# 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. By default 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,"scope":"country"}

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.

Choosing the routing scope

Country affinity is the default because it keeps traffic domestic, which is usually what data-residency-sensitive workloads want. When raw proximity matters more than staying in-country, pass scope=global to let the router cross borders:

scope	Behavior
country (default)	Nearest edge in the caller’s own country; crosses the border only if that country has no edge.
global	Nearest edge worldwide, ignoring borders.

# A Detroit caller: country scope stays in the US, global scope takes Toronto.
curl "https://autorouter.polargrid.ai/v1/route?scope=global"
# → {"region":"yto-01",...,"scope":"global"}

Unrecognized values fall back to country, so a typo can never silently widen routing to another country. The response echoes the scope that was actually applied — check it if you need to confirm your request was honored rather than silently defaulted.

scope=global opts out of country affinity and the network-aware on-ramp preference applied to callers whose country has no edge. It ranks purely by distance plus edge queue depth — the same load term the default uses — with no network-topology awareness. Great-circle distance is not always the lowest-latency choice across oceans, so benchmark before switching long-haul traffic to global.

Both SDKs expose this as a client option:

const client = await PolarGrid.create({ apiKey, routingScope: 'global' });

client = await PolarGrid.create(api_key=api_key, routing_scope="global")

Routing to a warm model

Discovery can also narrow candidates to edges that already have a specific model loaded, so your first request hits a warm node instead of paying a dynamic model load. Model availability is a hard filter; scope then picks the nearest among the nodes that qualify — the two options compose:

const client = await PolarGrid.create({
  apiKey,
  routingModel: 'kokoro',      // only edges with kokoro READY
  routingScope: 'global',      // nearest such edge worldwide
});

client = await PolarGrid.create(
    api_key=api_key,
    routing_model="kokoro",
    routing_scope="global",
)

curl "https://autorouter.polargrid.ai/v1/route?model=kokoro&scope=global"

If no edge currently serves the model, the raw endpoint returns 404; the SDKs catch that and fall back to the default edge (uncached — the miss is transient) so connecting still succeeds. The first request then triggers a dynamic model load instead of hitting a warm node.

These options are ignored when you pin a region or baseUrl — those bypass the autorouter entirely. Each scope/model combination is cached separately, so switching either re-asks the router rather than reusing another combination’s answer.

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