# List regions `GET /apis/cra.diagrid.io/v1beta2/regions` List the regions available to your organization. ## Responses ### 200 — The list of regions. `application/json` - `apiVersion` (string) - `items` (object[]) - `apiVersion` (string) - `kind` (string) - `metadata` (object) - `name` (string) - `uid` (string) - `resourceVersion` (integer) - `createdAt` (string) - `updatedAt` (string) - `deletedAt` (string) - `labels` (object) - `annotations` (object) - `spec` (object) - `type` (string) — Required. Read-only. Type is "public" or "private". Server-derived: creates set it from the endpoint used and ignore the client-supplied value. - `useJoinToken` (boolean) - `host` (string) - `location` (string) - `ingress` (string) — Ingress is the region ingress URL, in the format https://*.domain.com:port. It specifies whether the ingress uses TLS, the wildcard domain, and the port. - `clusters` (object[]) - `name` (string) - `exposeTunnel` (boolean) — ExposeTunnel enables tunnel-based access to the region's management API. Only valid for private regions. - `managedDomain` (boolean) — ManagedDomain indicates that Diagrid manages the domain for this region and directs traffic to it. - `supportPlan` (string) — SupportPlan is the support tier purchased with the region. "standard" is only offered on Diagrid-managed dedicated regions; regions on customer infrastructure (self-managed clusters, BYOC accounts) start at "select". One of: `standard`, `select`, `premium`. - `commitment` (string) — Write-only. Commitment is how the region is purchased: "monthly" (pay as you go, the default) or "annual" (prepay twelve months at a discount). It applies to every region kind — BYOC regions are purchased on a commitment too. Empty means monthly. Choosing "annual" purchases twelve months of this region up front unless the organization already has spare prepaid capacity that covers it, in which case nothing is charged. Whether annual can be purchased depends on how the organization pays and on what it is buying; the request is refused with an explanation when it cannot. Write-only: it is an input, and there is no cadence on the region to read back. Which regions an annual commitment covers is answered by the organization's subscription, where the commitment lives. One of: `monthly`, `annual`. - `commitmentUpgrade` (boolean) — Write-only. CommitmentUpgrade is the explicit acknowledgement that resizing a region covered by an annual commitment should also UPGRADE that commitment, and charge the prorated difference for the remainder of its term. Resizing a covered region to a larger configuration is refused without it, because coverage matches the exact configuration purchased: the resize would otherwise move the region out of the commitment and onto monthly list price while the prepayment sat unused. Set it and the commitment is upgraded, the difference is charged, and the region is resized as one operation. The commitment's term dates do not change. It is ignored on create, on a region no commitment covers, and on a resize to a smaller configuration (which is refused outright — the larger capacity has already been paid for and the difference is not refundable). - `dedicated` (object) — Write-only. DedicatedSpec is the customer-facing intent for a managed dedicated region. The customer expresses where (cloud/region) and how big (tier); Diagrid owns which account the region lives in and everything inside it. - `cloudProvider` (string) — Required. Immutable. CloudProvider and CloudRegion select where Diagrid provisions the region. Immutable after creation (relocating a tenant is a migration, not an update). One of: `aws`, `azure`. - `cloudRegion` (string) — Required. Immutable. - `tier` (string) — Required. Tier is an SME-oriented sizing preset mapping to a node-pool / data-store profile. During a trial the region runs on the trial footprint regardless of the tier selected; once a paid subscription starts it resizes to, and is billed at, the tier chosen here. One of: `small`, `medium`, `large`, `xlarge`. - `exposure` (string) — Exposure is the ingress posture for the region: "public" (internet-facing gateway load balancer, the default) or "private" (internal load balancer, reachable only over an AWS PrivateLink endpoint service — see PrivateLink). Surfaced to users as "Networking" (the UI label, and the CLI's --networking flag); the wire name stays "exposure" so existing consumers keep working. One of: `private`, `public`. - `privateLink` (object) — PrivateLinkSpec names the single customer account permitted to open a private link to a private dedicated region. Exactly one field is set, and which one depends on the region's cloud: the two are not interchangeable, and neither is optional for the cloud it belongs to. - One of: - **option 1** - **option 2** - `encryption` (object) — EncryptionSpec references the customer's KMS key used as the envelope (KEK) for the region's data-store data keys. - `kmsKeyArn` (string) — AWS. - `kmsKey` (string) — GCP KMS resource name. - `roleArn` (string) — RoleARN is the customer IAM role Diagrid assumes to use the key, gated by ExternalID (confused-deputy protection). - `externalId` (string) - `cloudConnection` (string) — Immutable. CloudConnection names the CloudProviderConnection the region provisions through — i.e. which customer cloud account it lives in. Optional: empty means the Diagrid-owned account. Immutable after creation. - `regionGroup` (string) — Read-only. RegionGroup is the name of the region group this region is a member of, if any. Set by the platform when the region joins a group; it cannot be written through this API. - `blockedAt` (string (date-time)) — BlockedAt indicates the region is blocked. - `blockReason` (string) - `status` (object) - `status` (string) — Status is the current processing status of the resource. - `updatedAt` (string) — UpdatedAt is the time of the last status update. - `messages` (object[]) — Messages contains any status messages, such as error details. - `message` (string) - `ingressAddresses` (string[]) — IngressAddresses lists the region's ingress IP addresses or domains. A region may have multiple hosts, each with its own ingress, so all of them are listed here. - `egressAddresses` (string[]) — EgressAddresses lists the region's egress IP addresses, which are common to all hosts in the region. Allow-list these if your application restricts inbound traffic by source address. - `endpoints` (object) - `metrics` (string) — Metrics is the region's metrics endpoint. - `logs` (string) - `controlplaneHttp` (string) - `controlplaneGrpc` (string) - `sentry` (string) - `events` (string) - `management` (string) — Management is the endpoint of the region's Management REST API. - `managementDiagrid` (string) — ManagementDiagrid is a Diagrid-owned domain that maps to the region's Management API. Only set for private regions. - `tunnelEndpointId` (string) — TunnelEndpointID identifies the tunnel endpoint for regions with exposeTunnel enabled. Clients send it in the tunnel routing header to reach the correct tunnel when connecting to the region. - `oidc` (string) — OIDC is the region's public OIDC issuer URL, serving the discovery documents (openid-configuration, JWKS) for workload identities minted in the region. Use it as-is for OIDC discovery — e.g. to verify the region's JWT-SVIDs or to register the region as a federated identity provider. - `trustAnchors` (string) — TrustAnchors is the HTTP endpoint serving a certificate authority bundle (PEM) for verifying this region's workload identities. To verify a workflow-history archive, use status.workflowSigningAnchors instead. - `trustAnchors` (string) — TrustAnchors is the in-region dataplane Sentry CA bundle (PEM) the host submitted at join, which verifies in-region workload identities. Present only for regions joined with a CA. - `workflowSigningAnchors` (string) — WorkflowSigningAnchors is the certificate authority bundle (PEM) that verifies the signing certificates on this region's workflow-history archives. Use it as the trust anchor when verifying an archive offline. It may contain more than one authority; X.509 path building selects the one that issued the archive's certificate chain. - `lastUpdatedAt` (string) - `connected` (boolean) - `daprVersion` (string) — DaprVersion is the Dapr version running in the region. - `connectionState` (string) — ConnectionState is live reachability ("joining"/"online"/"offline"); distinct from lifecycle `status` and from the sticky `connected` join marker. - `lastConnectionStateTransitionTime` (string) - `heartbeat` (object) - `lastHeartbeatAt` (string) - `agentVersion` (string) - `uptimeSeconds` (integer (int64)) — No omitempty: an agent's first heartbeat fires at startup with sub-second uptime, which truncates to 0 — a real value, not absent data. - `intervalSeconds` (integer (int64)) - `writable` (boolean) — Writable is whether the region's database accepts writes, as the region last reported it. In a region group the member whose database is writable is the active one, and a member running on a read-only replica reports false. Absent means the region is not reporting it: it is not in a region group, or it has stopped sending heartbeats. That is not the same answer as false. - `clusters` (object[]) - `name` (string) - `status` (string) - `joinTokenConsumnedAt` (string) - `lastUpdatedAt` (string) - `metadata` (object) — Agent environment metadata. - `negotiatedApiVersion` (integer (int32)) - `connectionState` (string) — Per-cluster liveness; region-level ConnectionState is the worst of these. - `heartbeat` (object) - `lastHeartbeatAt` (string) - `agentVersion` (string) - `uptimeSeconds` (integer (int64)) — No omitempty: an agent's first heartbeat fires at startup with sub-second uptime, which truncates to 0 — a real value, not absent data. - `intervalSeconds` (integer (int64)) - `writable` (boolean) — Writable is what this cluster reports about the region's database. The region-level writable is true only when every one of its clusters reports writable: they share one database and normally agree, and where they do not, the region is not one this control plane will place a write on. A cluster that has stopped heartbeating reports nothing, which leaves the region reporting nothing rather than read-only. - `messages` (object[]) — Messages explain a cluster whose status is not "ready" — for a private region, which of its management certificates is still outstanding, and so why the region's management API is not reachable yet. The region-level status.messages describes the region as a whole and does not carry this; without these the per-cluster status is a bare word. - `message` (string) - `supportsManagedPubSub` (boolean) - `supportsManagedKVStore` (boolean) - `supportsWorkflows` (boolean) - `supportsWorkflowHistorySigning` (boolean) - `dedicated` (object) — DedicatedStatus reflects the intent a dedicated region was created (or last updated) with, plus its provisioning phase. It is read-only: the intent is written through spec.dedicated on create/update. - `cloudProvider` (string) — CloudProvider and CloudRegion are where the region is provisioned. - `cloudRegion` (string) - `cloudConnection` (string) — CloudConnection names the CloudProviderConnection the region provisions through — i.e. which customer cloud account it lives in. Empty means the Diagrid-owned account. Mirrors the intent given as spec.dedicated.cloudConnection at creation, so a BYOC region's account is visible on read (spec.dedicated is write-only). - `tier` (string) — Tier is the region's sizing preset. - `exposure` (string) — Exposure is the region's ingress posture: "private" or "public". - `endpointServiceName` (string) — EndpointServiceName is what a private region is reached through, once provisioned: on AWS the PrivateLink VPC endpoint service name (e.g. "com.amazonaws.vpce.eu-west-1.vpce-svc-0abc123"), on Azure the Private Link Service alias (e.g. "pls-0123456789ab..westeurope.azure.privatelinkservice"). Point an interface VPC endpoint or a private endpoint at it; it auto-accepts connections from the allowed account or subscription below only. - `allowedAccountId` (string) — AllowedAccountID is the AWS account the endpoint service auto-accepts PrivateLink connections from. Present only for private AWS regions. - `allowedSubscriptionId` (string) — AllowedSubscriptionID is the Azure subscription the Private Link Service is visible to and auto-approves private endpoint connections from. Present only for private Azure regions. spec.dedicated is write-only, so without this there is no way at all - for the customer or for support - to read back which subscription a private Azure region admits. - `phase` (string) — Phase is the provisioning lifecycle phase (e.g. "Provisioning", "Deploying", "Ready"). - `provisioningMessage` (string) — ProvisioningMessage is the cloud provider's own explanation of why provisioning is not progressing, when it has given one - an unavailable SKU, an exhausted quota, a region the subscription may not provision in. Empty while a region is simply still building. - `subPhase` (string) — SubPhase refines the "Provisioning" phase with the infrastructure stage currently being provisioned: "Network", "Identity" or "KubernetesCluster". Empty once provisioning is complete. - `progressPercent` (integer) — ProgressPercent is the share (0-100) of the region's infrastructure resources that are fully provisioned. - `usage` (object) — UsageStatus is the region's CPU-usage measurement. All CPU values are in millicores (the region-wide sum of Catalyst-managed pod CPU). The rolling windows are the p95 of the region total over the past 1, 7 and 28 days. - `status` (string) — Status is the freshness classification: "notAvailable" (no usage data in Cortex yet), "active" (recent measurement) or "stalled" (measurement went stale). - `lastMeasureTime` (string) — LastMeasureTime is the measurement time of the newest sample. - `latest` (integer (int64)) — Latest is the latest region CPU (millicores), smoothed over 5 minutes. - `rolling1d` (integer (int64)) — Rolling1d is the p95 region CPU (millicores) over the past 1 day. - `rolling7d` (integer (int64)) — Rolling7d is the p95 region CPU (millicores) over the past 7 days. - `rolling28d` (integer (int64)) — Rolling28d is the p95 region CPU (millicores) over the past 28 days. - `kind` (string) - `metadata` (object) ### default — Unexpected error. `application/json` In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. `application/vnd.api+json` JSONAPI.org specification error response wrapper for UI. - `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. - `meta` (object) — Link members related to the primary data. - One of: - **string (uri-reference)** — A string containing the link's URL. - **object** - `href` (string (uri-reference)) — Required. A string containing the link's URL. - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship. - `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.