---
title: Search for available domains
---

[Skip to content](#_top)

[API Reference](https://developers.cloudflare.com/api/python)

[Registrar Sandbox](https://developers.cloudflare.com/api/python/resources/registrar_sandbox)

Copy Markdown

Open in **Claude**Open in **ChatGPT**Open in **Cursor**

---

**Copy Markdown****View as Markdown**

# Search for available domains

registrar\_sandbox.search(RegistrarSandboxSearchParams\*\*kwargs) -> [RegistrarSandboxSearchResponse](<https://developers.cloudflare.com/api/python/resources/registrar_sandbox#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)>)

GET/accounts/{account\_id}/registrar-sandbox/domain-search

Searches for domain name suggestions based on a keyword, phrase, or partial domain name. Returns a list of potentially available domains with pricing information.

**Important:** Results are non-authoritative and based on cached data. Always use the `/domain-check` endpoint to verify real-time availability before attempting registration.

Suggestions are scoped to extensions supported for programmatic registration via this API (`POST /registrations`). Domains on unsupported extensions will not appear in results, even if they are available at the registry level.

### Use cases

- Brand name discovery (e.g., “acme corp” → acmecorp.com, acmecorp.dev)
- Keyword-based suggestions (e.g., “coffee shop” → coffeeshop.com, mycoffeeshop.net)
- Alternative extension discovery (e.g., “example.com” → example.com, example.app, example.xyz)

### Workflow

1. Call this endpoint with a keyword or domain name.
2. Present suggestions to the user.
3. Call `/domain-check` with the user’s chosen domains to confirm real-time availability and pricing.
4. Proceed to `POST /registrations` only for supported non-premium domains where the Check response returns `registrable: true`.

**Note:** Searching with just a domain extension (e.g., “com” or “.app”) is not supported. Provide a keyword or domain name.

##### Security

<details>

<summary>API Token</summary>



The preferred authorization scheme for interacting with the Cloudflare API. <a href="https://developers.cloudflare.com/fundamentals/api/get-started/create-token/">Create a token</a>.

**Example:**<code>Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY</code>

</details>

<details>

<summary>API Email + API Key</summary>



The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

**Example:**<code>X-Auth-Email: user@example.com</code>

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

**Example:**<code>X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194</code>

</details>

##### ParametersExpand Collapse

account\_id: str

Identifier.

maxLength32

[Link to this property](<#(resource)%20registrar_sandbox%20%3E%20(method)%20search%20%3E%20(params)%20default%20%3E%20(param)%20account_id%20%3E%20(schema)>)

q: str

The search term to find domain suggestions. Accepts keywords, phrases, or full domain names.

- Phrases: “coffee shop” returns coffeeshop.com, mycoffeeshop.net, etc.
- Domain names: “example.com” returns example.com and variations across extensions

maxLength100

minLength1

[Link to this property](<#(resource)%20registrar_sandbox%20%3E%20(method)%20search%20%3E%20(params)%20default%20%3E%20(param)%20q%20%3E%20(schema)>)

extensions: Optional\[Sequence\[str]]

Limits results to specific domain extensions from the supported set. If not specified, returns results across all supported extensions. Extensions not in the supported set are silently ignored.

[Link to this property](<#(resource)%20registrar_sandbox%20%3E%20(method)%20search%20%3E%20(params)%20default%20%3E%20(param)%20extensions%20%3E%20(schema)>)

limit: Optional\[int]

Maximum number of domain suggestions to return. Defaults to 20 if not specified.

maximum50

minimum1

[Link to this property](<#(resource)%20registrar_sandbox%20%3E%20(method)%20search%20%3E%20(params)%20default%20%3E%20(param)%20limit%20%3E%20(schema)>)

##### ReturnsExpand Collapse

<details>

<summary>

class RegistrarSandboxSearchResponse: …

Contains the search results.

</summary>

<details>

<summary>

domains: List\[Domain]

Lists domain suggestions in relevance order. An empty array indicates that the search criteria matched zero domains.

</summary>

name: str

The fully qualified domain name (FQDN) in punycode format for internationalized domain names (IDNs).

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20name">Link to this property</a>

registrable: bool

Indicates domain availability according to potentially stale, non-authoritative search data.

- <code>true</code>: The domain appears available. Use POST /domain-check to confirm before registration.
- <code>false</code>: Search results mark the domain ineligible for registration through this API. See <code>reason</code> for details.

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20registrable">Link to this property</a>

<details>

<summary>

pricing: Optional\[DomainPricing]

Provides annual pricing information for a given domain. The API returns all per-year prices as strings to preserve decimal precision.

<code>renewal_cost</code> and <code>registration_cost</code> or <code>transfer_cost</code> are frequently the same value, but may differ due to premium rates for certain domains.

For a multi-year operations, the operation’s cost applies to the first year and <code>renewal_cost</code> applies to each subsequent year. The values reflect the current registry rate, which can change over time.

</summary>

currency: str

ISO-4217 currency code for the prices (e.g., “USD”, “EUR”, “GBP”).

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20pricing%20%3E%20(property)%20currency">Link to this property</a>

registration\_cost: str

The first-year cost to register this domain.

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20pricing%20%3E%20(property)%20registration_cost">Link to this property</a>

renewal\_cost: str

Per-year renewal cost for this domain. Applied to each year beyond the first year of a multi-year registration, and to each annual auto-renewal thereafter. May differ from <code>registration_cost</code>, especially for premium domains where initial registration often costs more than renewals.

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20pricing%20%3E%20(property)%20renewal_cost">Link to this property</a>

</details>

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20pricing">Link to this property</a>

<details>

<summary>

reason: Optional\[Literal\["extension\_not\_supported\_via\_api", "extension\_not\_supported", "extension\_disallows\_registration", 2 more]]

Appears only when <code>registrable</code> is <code>false</code> and explains the advisory search result. Use POST /domain-check for authoritative status.

- <code>extension_not_supported_via_api</code>: Cloudflare Registrar supports this extension in the dashboard but currently excludes it from programmatic registration through this API.
- <code>extension_not_supported</code>: Cloudflare Registrar excludes this extension entirely.
- <code>extension_disallows_registration</code>: The extension’s registry temporarily or permanently freezes new registrations.
- <code>domain_premium</code>: The domain carries premium pricing. This API currently supports standard registrations only.
- <code>domain_unavailable</code>: The domain appears unavailable.

</summary>

One of the following:

"extension\_not\_supported\_via\_api"

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20reason%20%3E%20(member)%200">Link to this property</a>

"extension\_not\_supported"

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20reason%20%3E%20(member)%201">Link to this property</a>

"extension\_disallows\_registration"

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20reason%20%3E%20(member)%202">Link to this property</a>

"domain\_premium"

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20reason%20%3E%20(member)%203">Link to this property</a>

"domain\_unavailable"

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20reason%20%3E%20(member)%204">Link to this property</a>

</details>

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20reason">Link to this property</a>

<details>

<summary>

tier: Optional\[Literal\["standard", "premium"]]

The pricing tier for this domain. A <code>registrable</code> value of <code>true</code> always includes this field, which defaults to <code>standard</code> for most domains. A <code>registrable</code> value of <code>false</code> may omit it.

- <code>standard</code>: Standard registry pricing.
- <code>premium</code>: Premium domain with higher pricing from the registry.

</summary>

One of the following:

"standard"

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20tier%20%3E%20(member)%200">Link to this property</a>

"premium"

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20tier%20%3E%20(member)%201">Link to this property</a>

</details>

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains%20%3E%20(items)%20%3E%20(property)%20tier">Link to this property</a>

</details>

<a href="#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)%20%3E%20(property)%20domains">Link to this property</a>

</details>

[Link to this property](<#(resource)%20registrar_sandbox%20%3E%20(model)%20registrar_sandbox_search_response%20%3E%20(schema)>)

### Search for available domains

Python

HTTPTypeScriptPythonGoTerraform

```
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.registrar_sandbox.search(
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    q="x",
)
print(response.domains)
```

200 example

200 example

200 example

200 example

200 example

400 example

400 example

```
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "acmecorp.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "acmecorp.dev",
        "pricing": {
          "currency": "USD",
          "registration_cost": "10.11",
          "renewal_cost": "10.11"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "acmecorp.app",
        "pricing": {
          "currency": "USD",
          "registration_cost": "11.00",
          "renewal_cost": "11.00"
        },
        "registrable": true,
        "tier": "standard"
      }
    ]
  },
  "success": true
}
```

```
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "bestpizza.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "bestpizza.net",
        "pricing": {
          "currency": "USD",
          "registration_cost": "9.95",
          "renewal_cost": "9.95"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "bestpizzashop.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      }
    ]
  },
  "success": true
}
```

```
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "coffeeshop.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "coffeeshoponline.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "mycoffeeshop.net",
        "pricing": {
          "currency": "USD",
          "registration_cost": "9.95",
          "renewal_cost": "9.95"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "thecoffeeshop.shop",
        "pricing": {
          "currency": "USD",
          "registration_cost": "11.00",
          "renewal_cost": "11.00"
        },
        "registrable": true,
        "tier": "standard"
      }
    ]
  },
  "success": true
}
```

```
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": []
  },
  "success": true
}
```

```
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "crypto.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "100000.00",
          "renewal_cost": "5000.00"
        },
        "registrable": true,
        "tier": "premium"
      },
      {
        "name": "cryptotrading.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "mycrypto.net",
        "pricing": {
          "currency": "USD",
          "registration_cost": "9.95",
          "renewal_cost": "9.95"
        },
        "registrable": true,
        "tier": "standard"
      }
    ]
  },
  "success": true
}
```

```
{
  "errors": [
    {
      "code": 1002,
      "message": "Parameter q exceeds maximum length of 100 characters"
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

```
{
  "errors": [
    {
      "code": 1001,
      "message": "Missing required parameter: q"
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

##### Returns Examples

200 example

200 example

200 example

200 example

200 example

400 example

400 example

```
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "acmecorp.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "acmecorp.dev",
        "pricing": {
          "currency": "USD",
          "registration_cost": "10.11",
          "renewal_cost": "10.11"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "acmecorp.app",
        "pricing": {
          "currency": "USD",
          "registration_cost": "11.00",
          "renewal_cost": "11.00"
        },
        "registrable": true,
        "tier": "standard"
      }
    ]
  },
  "success": true
}
```

```
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "bestpizza.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "bestpizza.net",
        "pricing": {
          "currency": "USD",
          "registration_cost": "9.95",
          "renewal_cost": "9.95"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "bestpizzashop.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      }
    ]
  },
  "success": true
}
```

```
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "coffeeshop.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "coffeeshoponline.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "mycoffeeshop.net",
        "pricing": {
          "currency": "USD",
          "registration_cost": "9.95",
          "renewal_cost": "9.95"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "thecoffeeshop.shop",
        "pricing": {
          "currency": "USD",
          "registration_cost": "11.00",
          "renewal_cost": "11.00"
        },
        "registrable": true,
        "tier": "standard"
      }
    ]
  },
  "success": true
}
```

```
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": []
  },
  "success": true
}
```

```
{
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "crypto.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "100000.00",
          "renewal_cost": "5000.00"
        },
        "registrable": true,
        "tier": "premium"
      },
      {
        "name": "cryptotrading.com",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        },
        "registrable": true,
        "tier": "standard"
      },
      {
        "name": "mycrypto.net",
        "pricing": {
          "currency": "USD",
          "registration_cost": "9.95",
          "renewal_cost": "9.95"
        },
        "registrable": true,
        "tier": "standard"
      }
    ]
  },
  "success": true
}
```

```
{
  "errors": [
    {
      "code": 1002,
      "message": "Parameter q exceeds maximum length of 100 characters"
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```

```
{
  "errors": [
    {
      "code": 1001,
      "message": "Missing required parameter: q"
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
```