domain_search
Creates, updates, deletes, gets or lists a domain_search resource.
Overview
| Name | domain_search |
| Type | Resource |
| Id | cloudflare.registrar.domain_search |
Fields
The following fields are returned by SELECT queries:
- list
Successfully returned domain search results.
| Name | Datatype | Description |
|---|---|---|
name | string | The fully qualified domain name (FQDN) in punycode format for internationalized domain names (IDNs). (example: example.com) |
pricing | object | Annual pricing information for a registrable domain. This object is only present when registrable is true. All prices are per year and returned as strings to preserve decimal precision. registration_cost and renewal_cost are frequently the same value, but may differ — especially for premium domains where registries set different rates for initial registration vs. renewal. For a multi-year registration (e.g., 4 years), the first year is charged at registration_cost and each subsequent year at renewal_cost. Registry pricing may change over time; the values returned here reflect the current registry rate. Premium pricing may be surfaced by Search and Check, but premium registration is not currently supported by this API. |
reason | string | Present only when registrable is false on search results. Explains why the domain does not appear registrable through this API. These values are advisory; use POST /domain-check for authoritative status. - extension_not_supported_via_api: Cloudflare Registrar supports this extension in the dashboard but it is not yet available for programmatic registration via this API. - extension_not_supported: This extension is not supported by Cloudflare Registrar at all. - extension_disallows_registration: The extension's registry has temporarily or permanently frozen new registrations. - domain_premium: The domain is premium priced. Premium registration is not currently supported by this API. - domain_unavailable: The domain appears unavailable. (extension_not_supported_via_api, extension_not_supported, extension_disallows_registration, domain_premium, domain_unavailable) (example: domain_unavailable) |
registrable | boolean | Indicates whether this domain appears available based on search data. Search results are non-authoritative and may be stale. - true: The domain appears available. Use POST /domain-check to confirm before registration. - false: The domain does not appear available in search results. |
tier | string | The pricing tier for this domain. Always present when registrable is true; defaults to standard for most domains. May be absent when registrable is false. - standard: Standard registry pricing - premium: Premium domain with higher pricing set by the registry (standard, premium) (example: standard) |
Methods
The following methods are available for this resource:
| Name | Accessible by | Required Params | Optional Params | Description |
|---|---|---|---|---|
list | select | account_id | q, extensions, limit | 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. |
Parameters
Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.
| Name | Datatype | Description |
|---|---|---|
account_id | string | The Cloudflare account ID. |
extensions | array | 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. |
limit | integer | Maximum number of domain suggestions to return. Defaults to 20 if not specified. |
q | string | 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 |
SELECT examples
- list
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.
SELECT
name,
pricing,
reason,
registrable,
tier
FROM cloudflare.registrar.domain_search
WHERE account_id = '{{ account_id }}' -- required
AND q = '{{ q }}'
AND extensions = '{{ extensions }}'
AND limit = '{{ limit }}'
;