# Origin Cloud Regions

## List origin cloud region mappings

`client.Cache.OriginCloudRegions.List(ctx, params) (*V4PagePaginationArray[OriginCloudRegion], error)`

**get** `/zones/{zone_id}/origin/cloud_regions`

Returns all IP-to-cloud-region mappings configured for the zone with pagination support. Each mapping tells Cloudflare which cloud vendor and region hosts the origin at that IP, enabling the edge to route via the nearest Tiered Cache upper-tier co-located with that cloud provider. Returns an empty array when no mappings exist.

### Parameters

- `params OriginCloudRegionListParams`

  - `ZoneID param.Field[string]`

    Path param: Identifier.

  - `Page param.Field[int64]`

    Query param: Page number of paginated results.

  - `PerPage param.Field[int64]`

    Query param: Number of items per page.

### Returns

- `type OriginCloudRegion struct{…}`

  A single origin IP-to-cloud-region mapping.

  - `OriginIP string`

    The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for IPv6).

  - `Region string`

    Cloud vendor region identifier.

  - `Vendor OriginCloudRegionVendor`

    Cloud vendor hosting the origin.

    - `const OriginCloudRegionVendorAws OriginCloudRegionVendor = "aws"`

    - `const OriginCloudRegionVendorAzure OriginCloudRegionVendor = "azure"`

    - `const OriginCloudRegionVendorGcp OriginCloudRegionVendor = "gcp"`

    - `const OriginCloudRegionVendorOci OriginCloudRegionVendor = "oci"`

  - `ModifiedOn Time`

    Time this mapping was last modified.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/cache"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  page, err := client.Cache.OriginCloudRegions.List(context.TODO(), cache.OriginCloudRegionListParams{
    ZoneID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": [],
  "result_info": {
    "count": 0,
    "page": 1,
    "per_page": 20,
    "total_count": 0,
    "total_pages": 0
  },
  "success": true
}
```

## Get an origin cloud region mapping

`client.Cache.OriginCloudRegions.Get(ctx, originIP, query) (*OriginCloudRegion, error)`

**get** `/zones/{zone_id}/origin/cloud_regions/{origin_ip}`

Returns the cloud region mapping for a single origin IP address. The IP path parameter is normalized before lookup (RFC 5952 for IPv6). Returns 404 if the zone has no mappings or if the specified IP has no mapping.

### Parameters

- `originIP string`

- `query OriginCloudRegionGetParams`

  - `ZoneID param.Field[string]`

    Identifier.

### Returns

- `type OriginCloudRegion struct{…}`

  A single origin IP-to-cloud-region mapping.

  - `OriginIP string`

    The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for IPv6).

  - `Region string`

    Cloud vendor region identifier.

  - `Vendor OriginCloudRegionVendor`

    Cloud vendor hosting the origin.

    - `const OriginCloudRegionVendorAws OriginCloudRegionVendor = "aws"`

    - `const OriginCloudRegionVendorAzure OriginCloudRegionVendor = "azure"`

    - `const OriginCloudRegionVendorGcp OriginCloudRegionVendor = "gcp"`

    - `const OriginCloudRegionVendorOci OriginCloudRegionVendor = "oci"`

  - `ModifiedOn Time`

    Time this mapping was last modified.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/cache"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  originCloudRegion, err := client.Cache.OriginCloudRegions.Get(
    context.TODO(),
    "192.0.2.1",
    cache.OriginCloudRegionGetParams{
      ZoneID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", originCloudRegion.OriginIP)
}
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "modified_on": "2026-03-01T12:00:00Z",
    "origin_ip": "192.0.2.1",
    "region": "us-east-1",
    "vendor": "aws"
  },
  "success": true
}
```

## Create or replace an origin cloud region mapping

`client.Cache.OriginCloudRegions.Update(ctx, originIP, params) (*OriginCloudRegion, error)`

**put** `/zones/{zone_id}/origin/cloud_regions/{origin_ip}`

Creates a new IP-to-cloud-region mapping or replaces the existing mapping for the specified IP. PUT is idempotent — calling it repeatedly with the same body produces the same result. The IP path parameter is normalized to canonical form (RFC 5952 for IPv6) before storage. The vendor and region are validated against the list from `GET /zones/{zone_id}/origin/cloud_regions/supported_regions`. Returns 400 if the `origin_ip` in the body does not match the URL path parameter. Returns 403 (code 1164) when the zone has reached the limit of 3,500 IP mappings.

### Parameters

- `originIP string`

- `params OriginCloudRegionUpdateParams`

  - `ZoneID param.Field[string]`

    Path param: Identifier.

  - `OriginIP param.Field[string]`

    Body param: Origin IP address (IPv4 or IPv6). For the single PUT endpoint (`PUT /origin/cloud_regions/{origin_ip}`), this field must match the path parameter or the request will be rejected with a 400 error. For the batch PUT endpoint, this field identifies which mapping to upsert.

  - `Region param.Field[string]`

    Body param: Cloud vendor region identifier. Must be a valid region for the specified vendor as returned by the supported_regions endpoint.

  - `Vendor param.Field[OriginCloudRegionUpdateParamsVendor]`

    Body param: Cloud vendor hosting the origin. Must be one of the supported vendors.

    - `const OriginCloudRegionUpdateParamsVendorAws OriginCloudRegionUpdateParamsVendor = "aws"`

    - `const OriginCloudRegionUpdateParamsVendorAzure OriginCloudRegionUpdateParamsVendor = "azure"`

    - `const OriginCloudRegionUpdateParamsVendorGcp OriginCloudRegionUpdateParamsVendor = "gcp"`

    - `const OriginCloudRegionUpdateParamsVendorOci OriginCloudRegionUpdateParamsVendor = "oci"`

### Returns

- `type OriginCloudRegion struct{…}`

  A single origin IP-to-cloud-region mapping.

  - `OriginIP string`

    The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for IPv6).

  - `Region string`

    Cloud vendor region identifier.

  - `Vendor OriginCloudRegionVendor`

    Cloud vendor hosting the origin.

    - `const OriginCloudRegionVendorAws OriginCloudRegionVendor = "aws"`

    - `const OriginCloudRegionVendorAzure OriginCloudRegionVendor = "azure"`

    - `const OriginCloudRegionVendorGcp OriginCloudRegionVendor = "gcp"`

    - `const OriginCloudRegionVendorOci OriginCloudRegionVendor = "oci"`

  - `ModifiedOn Time`

    Time this mapping was last modified.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/cache"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  originCloudRegion, err := client.Cache.OriginCloudRegions.Update(
    context.TODO(),
    "192.0.2.1",
    cache.OriginCloudRegionUpdateParams{
      ZoneID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
      OriginIP: cloudflare.F("192.0.2.1"),
      Region: cloudflare.F("us-east-1"),
      Vendor: cloudflare.F(cache.OriginCloudRegionUpdateParamsVendorAws),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", originCloudRegion.OriginIP)
}
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "modified_on": "2026-03-01T12:00:00Z",
    "origin_ip": "192.0.2.1",
    "region": "us-east-1",
    "vendor": "aws"
  },
  "success": true
}
```

## Delete an origin cloud region mapping

`client.Cache.OriginCloudRegions.Delete(ctx, originIP, body) (*OriginCloudRegionDeleteResponse, error)`

**delete** `/zones/{zone_id}/origin/cloud_regions/{origin_ip}`

Removes the cloud region mapping for a single origin IP address. The IP path parameter is normalized before lookup. Returns the deleted IP on success. Returns 404 if no mapping exists for the specified IP. When the last mapping for the zone is removed the underlying rule record is also deleted.

### Parameters

- `originIP string`

- `body OriginCloudRegionDeleteParams`

  - `ZoneID param.Field[string]`

    Identifier.

### Returns

- `type OriginCloudRegionDeleteResponse struct{…}`

  Response result for a delete operation. Identifies the deleted mapping.

  - `OriginIP string`

    The origin IP address whose mapping was deleted.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/cache"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  originCloudRegion, err := client.Cache.OriginCloudRegions.Delete(
    context.TODO(),
    "192.0.2.1",
    cache.OriginCloudRegionDeleteParams{
      ZoneID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", originCloudRegion.OriginIP)
}
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "origin_ip": "192.0.2.1"
  },
  "success": true
}
```

## Batch create or replace origin cloud region mappings

`client.Cache.OriginCloudRegions.BulkUpdate(ctx, params) (*OriginCloudRegionBulkUpdateResponse, error)`

**put** `/zones/{zone_id}/origin/cloud_regions/batch`

Upserts up to 100 IP-to-cloud-region mappings in a single request. Items in the request body are created or replaced; mappings not included in the request body are preserved unchanged (this is a merge operation, not a full collection replacement). Each item is validated independently — valid items are applied and invalid items are returned in the `failed` array. The vendor and region for every item are validated against the list from `GET /zones/{zone_id}/origin/cloud_regions/supported_regions`.

### Parameters

- `params OriginCloudRegionBulkUpdateParams`

  - `ZoneID param.Field[string]`

    Path param: Identifier.

  - `Body param.Field[[]OriginCloudRegionBulkUpdateParamsBody]`

    Body param

    - `OriginIP string`

      Origin IP address (IPv4 or IPv6). For the single PUT endpoint (`PUT /origin/cloud_regions/{origin_ip}`), this field must match the path parameter or the request will be rejected with a 400 error. For the batch PUT endpoint, this field identifies which mapping to upsert.

    - `Region string`

      Cloud vendor region identifier. Must be a valid region for the specified vendor as returned by the supported_regions endpoint.

    - `Vendor OriginCloudRegionBulkUpdateParamsBodyVendor`

      Cloud vendor hosting the origin. Must be one of the supported vendors.

      - `const OriginCloudRegionBulkUpdateParamsBodyVendorAws OriginCloudRegionBulkUpdateParamsBodyVendor = "aws"`

      - `const OriginCloudRegionBulkUpdateParamsBodyVendorAzure OriginCloudRegionBulkUpdateParamsBodyVendor = "azure"`

      - `const OriginCloudRegionBulkUpdateParamsBodyVendorGcp OriginCloudRegionBulkUpdateParamsBodyVendor = "gcp"`

      - `const OriginCloudRegionBulkUpdateParamsBodyVendorOci OriginCloudRegionBulkUpdateParamsBodyVendor = "oci"`

### Returns

- `type OriginCloudRegionBulkUpdateResponse struct{…}`

  Response result for a batch origin cloud region operation.

  - `Failed []OriginCloudRegionBulkUpdateResponseFailed`

    Items that could not be applied, with error details.

    - `OriginIP string`

      The origin IP address for this item.

    - `Error string`

      Error message explaining why the item failed. Present only on failed items.

    - `Region string`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `Vendor string`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

  - `Succeeded []OriginCloudRegionBulkUpdateResponseSucceeded`

    Items that were successfully applied.

    - `OriginIP string`

      The origin IP address for this item.

    - `Error string`

      Error message explaining why the item failed. Present only on failed items.

    - `Region string`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `Vendor string`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/cache"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.Cache.OriginCloudRegions.BulkUpdate(context.TODO(), cache.OriginCloudRegionBulkUpdateParams{
    ZoneID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    Body: []cache.OriginCloudRegionBulkUpdateParamsBody{cache.OriginCloudRegionBulkUpdateParamsBody{
      OriginIP: cloudflare.F("192.0.2.1"),
      Region: cloudflare.F("us-east-1"),
      Vendor: cloudflare.F(cache.OriginCloudRegionBulkUpdateParamsBodyVendorAws),
    }, cache.OriginCloudRegionBulkUpdateParamsBody{
      OriginIP: cloudflare.F("2001:db8::1"),
      Region: cloudflare.F("us-central1"),
      Vendor: cloudflare.F(cache.OriginCloudRegionBulkUpdateParamsBodyVendorGcp),
    }},
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Failed)
}
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "failed": [],
    "succeeded": [
      {
        "origin_ip": "192.0.2.1",
        "region": "us-east-1",
        "vendor": "aws"
      },
      {
        "origin_ip": "2001:db8::1",
        "region": "us-central1",
        "vendor": "gcp"
      }
    ]
  },
  "success": true
}
```

## Batch delete origin cloud region mappings

`client.Cache.OriginCloudRegions.BulkDelete(ctx, body) (*OriginCloudRegionBulkDeleteResponse, error)`

**delete** `/zones/{zone_id}/origin/cloud_regions/batch`

Removes up to 100 IP-to-cloud-region mappings in a single request. Each IP is validated independently — successfully deleted items are returned in the `succeeded` array and IPs that could not be found or are invalid are returned in the `failed` array.

### Parameters

- `body OriginCloudRegionBulkDeleteParams`

  - `ZoneID param.Field[string]`

    Identifier.

### Returns

- `type OriginCloudRegionBulkDeleteResponse struct{…}`

  Response result for a batch origin cloud region operation.

  - `Failed []OriginCloudRegionBulkDeleteResponseFailed`

    Items that could not be applied, with error details.

    - `OriginIP string`

      The origin IP address for this item.

    - `Error string`

      Error message explaining why the item failed. Present only on failed items.

    - `Region string`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `Vendor string`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

  - `Succeeded []OriginCloudRegionBulkDeleteResponseSucceeded`

    Items that were successfully applied.

    - `OriginIP string`

      The origin IP address for this item.

    - `Error string`

      Error message explaining why the item failed. Present only on failed items.

    - `Region string`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `Vendor string`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/cache"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.Cache.OriginCloudRegions.BulkDelete(context.TODO(), cache.OriginCloudRegionBulkDeleteParams{
    ZoneID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Failed)
}
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "failed": [],
    "succeeded": [
      {
        "origin_ip": "192.0.2.1",
        "region": "us-east-1",
        "vendor": "aws"
      },
      {
        "origin_ip": "2001:db8::1",
        "region": "us-central1",
        "vendor": "gcp"
      }
    ]
  },
  "success": true
}
```

## List supported cloud vendors and regions

`client.Cache.OriginCloudRegions.SupportedRegions(ctx, query) (*OriginCloudRegionSupportedRegionsResponse, error)`

**get** `/zones/{zone_id}/origin/cloud_regions/supported_regions`

Returns the cloud vendors and regions that are valid values for origin cloud region mappings. Each region includes the Tiered Cache upper-tier colocation codes that will be used for cache routing when a mapping targeting that region is active. Requires the zone to have Tiered Cache enabled.

### Parameters

- `query OriginCloudRegionSupportedRegionsParams`

  - `ZoneID param.Field[string]`

    Identifier.

### Returns

- `type OriginCloudRegionSupportedRegionsResponse struct{…}`

  Cloud vendors and their supported regions for origin cloud region mappings.

  - `ObtainedCodes bool`

    Whether Cloudflare airport codes (IATA colo identifiers) were successfully resolved for the `upper_tier_colos` field on each region. When `false`, the `upper_tier_colos` arrays may be empty or incomplete.

  - `Vendors map[string, []OriginCloudRegionSupportedRegionsResponseVendor]`

    Map of vendor name to list of supported regions.

    - `Name string`

      Cloud vendor region identifier.

    - `UpperTierColos []string`

      Cloudflare Tiered Cache upper-tier colocation codes co-located with this cloud region. Requests from zones with a matching origin mapping will be routed through these colos.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/cache"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.Cache.OriginCloudRegions.SupportedRegions(context.TODO(), cache.OriginCloudRegionSupportedRegionsParams{
    ZoneID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.ObtainedCodes)
}
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "obtained_codes": true,
    "vendors": {
      "aws": [
        {
          "name": "us-east-1",
          "upper_tier_colos": [
            "IAD",
            "EWR"
          ]
        },
        {
          "name": "us-west-2",
          "upper_tier_colos": [
            "SEA"
          ]
        }
      ],
      "gcp": [
        {
          "name": "us-central1",
          "upper_tier_colos": [
            "ORD"
          ]
        }
      ]
    }
  },
  "success": true
}
```

## Domain Types

### Origin Cloud Region

- `type OriginCloudRegion struct{…}`

  A single origin IP-to-cloud-region mapping.

  - `OriginIP string`

    The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for IPv6).

  - `Region string`

    Cloud vendor region identifier.

  - `Vendor OriginCloudRegionVendor`

    Cloud vendor hosting the origin.

    - `const OriginCloudRegionVendorAws OriginCloudRegionVendor = "aws"`

    - `const OriginCloudRegionVendorAzure OriginCloudRegionVendor = "azure"`

    - `const OriginCloudRegionVendorGcp OriginCloudRegionVendor = "gcp"`

    - `const OriginCloudRegionVendorOci OriginCloudRegionVendor = "oci"`

  - `ModifiedOn Time`

    Time this mapping was last modified.