> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Add a Zone
Only users with **Admin** or **Ops** roles can perform this action.
This API can modify your account settings, damage your operations or incur charges.
Paste your API key to the authorization field. To get an API key, [Create an account](https://brightdata.com/?hs_signup=1\&utm_source=docs\&utm_campaign=playground) and learn [how to generate an API key](/api-reference/authentication#how-do-i-generate-a-new-api-key%3F)
## ISP proxy zone examples
Creating an ISP zone requires specific parameter combinations. The fields below are not optional. Omitting them will silently create the wrong zone type or billing plan.
Setting `zone.type` to `ISP` alone will create a **Datacenter zone**, not an ISP zone. You must also set `plan.pool_ip_type` to `static_res`. Country codes must be **lowercase** (e.g. `us`, `gb`). Uppercase codes return a misleading "no IPs available" error.
### Shared ISP (pay-per-GB)
```json theme={null}
{
"zone": { "name": "my_isp_zone", "type": "ISP" },
"plan": {
"type": "static",
"pool_ip_type": "static_res",
"ips_type": "shared",
"bandwidth": "bandwidth",
"country": "us"
}
}
```
### Shared ISP (unlimited bandwidth)
Setting `bandwidth: unlimited` alone **does not** activate unlimited billing. You must also include `unl_bw_tiers: std`.
```json theme={null}
{
"zone": { "name": "my_isp_zone", "type": "ISP" },
"plan": {
"type": "static",
"pool_ip_type": "static_res",
"ips_type": "shared",
"bandwidth": "unlimited",
"unl_bw_tiers": "std",
"country": "us"
}
}
```
### Dedicated ISP (unlimited bandwidth)
```json theme={null}
{
"zone": { "name": "my_isp_zone", "type": "ISP" },
"plan": {
"type": "static",
"pool_ip_type": "static_res",
"ips_type": "dedicated",
"bandwidth": "unlimited",
"unl_bw_tiers": "std",
"country": "us",
"ips": 10
}
}
```
## OpenAPI
````yaml api-reference/openapi POST /zone
openapi: 3.0.1
info:
title: Bright Data API
description: >-
Integrate Bright Data APIs to your pipeline and secure high-end scraping
precision
version: 1.0.0
servers:
- url: https://api.brightdata.com
security:
- bearerAuth: []
paths:
/zone:
post:
description: Add a new zone
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewZoneBody'
responses:
'201':
description: Zone added
components:
schemas:
NewZoneBody:
required:
- zone
- plan
type: object
properties:
zone:
$ref: '#/components/schemas/Zone'
plan:
$ref: '#/components/schemas/Plan'
Zone:
required:
- name
type: object
properties:
name:
description: The name of the zone
type: string
type:
description: Zone Type, e.g. serp, isp, mobile, etc.
type: string
example:
name: zone-name
type: serp
Plan:
oneOf:
- title: SERP API
description: Creates a SERP API zone for scraping search engine results.
type: object
required:
- type
- serp
properties:
type:
description: Must be `unblocker` for SERP API zones.
type: string
enum:
- unblocker
serp:
description: Must be `true` to create a SERP API zone.
type: boolean
enum:
- true
country:
description: >-
Lowercase ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`,
`sg`). **Must be lowercase** — uppercase codes will return a
misleading 'no IPs available' error. Use `any` to allow any
country.
type: string
default: any
solve_captcha_disable:
description: When set to `true` it will disable captcha solving.
type: boolean
default: true
custom_headers:
description: >-
When set to `true`, allows users to include custom headers in
their requests.
type: boolean
default: false
- title: Scraping Browser
description: Creates a Scraping Browser zone.
type: object
required:
- type
properties:
type:
description: Must be `browser_api` for Scraping Browser zones.
type: string
enum:
- browser_api
country:
description: >-
Lowercase ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`,
`sg`). **Must be lowercase** — uppercase codes will return a
misleading 'no IPs available' error. Use `any` to allow any
country.
type: string
default: any
custom_headers:
description: >-
When set to `true`, allows users to include custom headers in
their requests.
type: boolean
default: false
- title: Residential Proxy
description: Creates a Residential proxy zone.
type: object
required:
- type
properties:
type:
description: Must be `resident` for Residential proxy zones.
type: string
enum:
- resident
country:
description: >-
Lowercase ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`,
`sg`). **Must be lowercase** — uppercase codes will return a
misleading 'no IPs available' error. Use `any` to allow any
country.
type: string
default: any
city:
description: '`true` when enabling City targeting permission.'
type: boolean
default: false
asn:
description: '`true` when enabling ASN targeting permission.'
type: boolean
default: false
vip:
description: '`true` when allocating gIP (group of IPs).'
type: boolean
default: false
vips:
description: Number of gIP (group of IPs) to allocate to the zone.
type: integer
default: 0
vips_type:
description: Type of gIP allocation.
type: string
enum:
- shared
- domain
vip_country:
description: >-
Specify which country IP to allocate to the zone. Required when
`vip` is `true`.
type: string
vip_country_city:
description: >-
Country code followed by city (e.g. `se-stockholm`). Required
when `vip` is `true` and city targeting is needed.
type: string
default: any
ip_alloc_preset:
description: To set a zone with Shared - Pay per usage type.
type: string
enum:
- shared_block
- shared_res_block
domain_whitelist:
description: Space separated list of allowlisted domains
type: string
custom_headers:
description: >-
When set to `true`, allows users to include custom headers in
their requests.
type: boolean
default: false
- title: Mobile Proxy
description: >-
Creates a Mobile proxy zone. Uses `resident` plan type with `mobile:
true`.
type: object
required:
- type
- mobile
properties:
type:
description: Must be `resident` for Mobile proxy zones.
type: string
enum:
- resident
mobile:
description: Must be `true` to create a Mobile proxy zone.
type: boolean
enum:
- true
country:
description: >-
Lowercase ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`,
`sg`). **Must be lowercase** — uppercase codes will return a
misleading 'no IPs available' error. Use `any` to allow any
country.
type: string
default: any
city:
description: '`true` when enabling City targeting permission.'
type: boolean
default: false
vip:
description: '`true` when allocating gIP (group of IPs).'
type: boolean
default: false
vips:
description: Number of gIP (group of IPs) to allocate to the zone.
type: integer
default: 0
vips_type:
description: Type of gIP allocation.
type: string
enum:
- shared
- domain
custom_headers:
description: >-
When set to `true`, allows users to include custom headers in
their requests.
type: boolean
default: false
- title: ISP Proxy – Shared (Pay-per-GB)
description: >-
Creates a shared ISP proxy zone billed per GB. `pool_ip_type:
static_res` is required — omitting it silently creates a Datacenter
zone instead.
type: object
required:
- type
- pool_ip_type
- ips_type
- country
properties:
type:
description: Must be `static` for ISP proxy zones.
type: string
enum:
- static
pool_ip_type:
description: >-
Must be `static_res` to create an ISP proxy zone. Default is
`dc` (Datacenter).
type: string
enum:
- static_res
ips_type:
description: Must be `shared` for this zone type.
type: string
enum:
- shared
country:
description: >-
Lowercase ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`,
`sg`). **Must be lowercase** — uppercase codes will return a
misleading 'no IPs available' error. Use `any` to allow any
country.
type: string
default: any
custom_headers:
description: >-
When set to `true`, allows users to include custom headers in
their requests.
type: boolean
default: false
- title: ISP Proxy – Shared (Unlimited Bandwidth)
description: >-
Creates a shared ISP proxy zone with unlimited bandwidth.
`unl_bw_tiers: std` is required — without it, `bandwidth: unlimited`
is silently ignored and the zone bills per GB.
type: object
required:
- type
- pool_ip_type
- ips_type
- bandwidth
- unl_bw_tiers
- country
properties:
type:
description: Must be `static` for ISP proxy zones.
type: string
enum:
- static
pool_ip_type:
description: Must be `static_res` to create an ISP proxy zone.
type: string
enum:
- static_res
ips_type:
description: Must be `shared` for this zone type.
type: string
enum:
- shared
bandwidth:
description: Must be `unlimited` to enable unlimited bandwidth billing.
type: string
enum:
- unlimited
unl_bw_tiers:
description: >-
**Required** to activate unlimited bandwidth billing. Without
this field the zone defaults to pay-per-GB even if `bandwidth:
unlimited` is set.
type: string
enum:
- std
country:
description: >-
Lowercase ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`,
`sg`). **Must be lowercase** — uppercase codes will return a
misleading 'no IPs available' error. Use `any` to allow any
country.
type: string
default: any
custom_headers:
description: >-
When set to `true`, allows users to include custom headers in
their requests.
type: boolean
default: false
- title: ISP Proxy – Dedicated
description: >-
Creates a dedicated ISP proxy zone with unlimited bandwidth and a
fixed number of IPs.
type: object
required:
- type
- pool_ip_type
- ips_type
- bandwidth
- unl_bw_tiers
- country
- ips
properties:
type:
description: Must be `static` for ISP proxy zones.
type: string
enum:
- static
pool_ip_type:
description: Must be `static_res` to create an ISP proxy zone.
type: string
enum:
- static_res
ips_type:
description: Must be `dedicated` for this zone type.
type: string
enum:
- dedicated
bandwidth:
description: Must be `unlimited` for dedicated ISP zones.
type: string
enum:
- unlimited
unl_bw_tiers:
description: '**Required** to activate unlimited bandwidth billing.'
type: string
enum:
- std
country:
description: >-
Lowercase ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`,
`sg`). **Must be lowercase** — uppercase codes will return a
misleading 'no IPs available' error. Use `any` to allow any
country.
type: string
default: any
country_city:
description: >-
Country code followed by city (e.g. `se-stockholm`) to target a
specific city.
type: string
default: any
ips:
description: Number of dedicated IPs to allocate to the zone.
type: integer
custom_headers:
description: >-
When set to `true`, allows users to include custom headers in
their requests.
type: boolean
default: false
- title: Datacenter Proxy – Shared
description: Creates a shared Datacenter proxy zone.
type: object
required:
- type
- ips_type
properties:
type:
description: Must be `static` for Datacenter proxy zones.
type: string
enum:
- static
pool_ip_type:
description: >-
Set to `dc` for Datacenter (default). Omitting this field also
defaults to Datacenter.
type: string
enum:
- dc
default: dc
ips_type:
description: Must be `shared` for this zone type.
type: string
enum:
- shared
country:
description: >-
Lowercase ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`,
`sg`). **Must be lowercase** — uppercase codes will return a
misleading 'no IPs available' error. Use `any` to allow any
country.
type: string
default: any
domain_whitelist:
description: Space separated list of allowlisted domains
type: string
custom_headers:
description: >-
When set to `true`, allows users to include custom headers in
their requests.
type: boolean
default: false
- title: Datacenter Proxy – Dedicated
description: >-
Creates a dedicated Datacenter proxy zone with a fixed number of
IPs.
type: object
required:
- type
- ips_type
- ips
properties:
type:
description: Must be `static` for Datacenter proxy zones.
type: string
enum:
- static
pool_ip_type:
description: Set to `dc` for Datacenter (default).
type: string
enum:
- dc
default: dc
ips_type:
description: Must be `dedicated` for this zone type.
type: string
enum:
- dedicated
ips:
description: Number of dedicated IPs to allocate to the zone.
type: integer
country:
description: >-
Lowercase ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`,
`sg`). **Must be lowercase** — uppercase codes will return a
misleading 'no IPs available' error. Use `any` to allow any
country.
type: string
default: any
country_city:
description: >-
Country code followed by city (e.g. `se-stockholm`) to target a
specific city.
type: string
default: any
domain_whitelist:
description: Space separated list of allowlisted domains
type: string
custom_headers:
description: >-
When set to `true`, allows users to include custom headers in
their requests.
type: boolean
default: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Use your Bright Data API Key as a Bearer token in the Authorization
header.
**How to authenticate:**
1. Obtain your API Key from the Bright Data account settings at
https://brightdata.com/cp/setting/users
2. Include the API Key in the Authorization header of your requests
3. Format: `Authorization: Bearer YOUR_API_KEY`
**Example:**
```
Authorization: Bearer
b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df
```
Learn how to get your Bright Data API key:
https://docs.brightdata.com/api-reference/authentication
bearerFormat: API Key
````