Skip to content
Cloudflare API
Start here
API Reference
Registrar Sandbox
Registration Status

Get Registration Status

registrar_sandbox.registration_status.get(strdomain_name, RegistrationStatusGetParams**kwargs) -> RegistrationStatusGetResponse
GET/accounts/{account_id}/registrar-sandbox/registrations/{domain_name}/registration-status

Returns the current status of a domain registration workflow.

Use this endpoint to poll for completion when the POST response returned 202 Accepted. The URL is provided in the links.self field of the workflow status response.

Poll this endpoint until the workflow reaches a terminal state or a state that requires user attention.

Terminal states: succeeded and failed are terminal and always have completed: true.

Non-terminal states:

  • action_required has completed: false and will not resolve on its own. The workflow is paused pending user intervention.
  • blocked has completed: false and indicates the workflow is waiting on a third party such as the extension registry or losing registrar. Continue polling while informing the user of the delay.

Use increasing backoff between polls. When state: blocked, use a longer polling interval and do not poll indefinitely.

A naive polling loop that only checks completed can run indefinitely when state: action_required. Break explicitly on action_required:

let status;
do {
  await new Promise(r => setTimeout(r, 2000));
  status = await cloudflare.request({
    method: 'GET',
    path: reg.result.links.self,
  });
} while (
  !status.result.completed &&
  status.result.state !== 'action_required'
);

if (status.result.state === 'action_required') {
  // Surface context.action and context.confirmation_sent_to to the user.
  // Do not re-submit the registration request.
}
Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

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

Example:X-Auth-Email: user@example.com

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

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
ParametersExpand Collapse
account_id: str

Identifier.

maxLength32
domain_name: str

Provides a fully qualified domain name (FQDN), including the extension (e.g., example.com, mybrand.app). The domain name uniquely identifies a registration. Cloudflare permits only one registration per domain, making the domain name a natural idempotency key for registration requests.

ReturnsExpand Collapse
class RegistrationStatusGetResponse: …

Status of an async registration workflow.

completed: bool

Indicates whether the workflow reached a terminal state. A succeeded or failed state returns true; pending, in_progress, action_required, and blocked return false.

created_at: datetime
formatdate-time
state: Literal["pending", "in_progress", "action_required", 3 more]

Describes the workflow lifecycle state.

  • pending: The workflow awaits processing.
  • in_progress: Processing started. Continue polling links.self. An internal deadline limits the duration of this state.
  • action_required: The workflow pauses for user action. See context.action for details. Stop automated polling until the user completes the required action.
  • blocked: A third party, such as the domain extension’s registry or a losing registrar, prevents progress. Continue polling because the block may resolve when the third party responds.
  • succeeded: Terminal state. The operation completed successfully. completed equals true. For registrations, context.registration contains the resulting registration resource.
  • failed: Terminal state. The operation failed. completed equals true. See error.code and error.message for the reason. Require user review before retrying.
One of the following:
"pending"
"in_progress"
"action_required"
"blocked"
"succeeded"
"failed"
updated_at: datetime
formatdate-time
context: Optional[Dict[str, object]]

Provides workflow-specific data.

For domain-centric workflows, context.domain_name identifies the workflow subject.

error: Optional[Error]

Provides error details when a workflow reaches the failed state. The workflow type (registration, update, etc.) and underlying registry response determine the specific codes and messages. Workflow error codes differ from immediate HTTP error errors[].code values in non-2xx responses. Surface error.message to the user for context.

code: str

Machine-readable error code identifying the failure reason.

message: str

Human-readable explanation of the failure. May include registry-specific details.

Get Registration Status

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
registration_status = client.registrar_sandbox.registration_status.get(
    domain_name="example.com",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(registration_status.completed)
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": false,
    "context": {
      "action": "registrant_email_confirmation_pending",
      "confirmation_sent_to": "a***@example.com",
      "domain_name": "example.com"
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "action_required",
    "updated_at": "2025-10-27T10:01:00Z"
  },
  "success": true
}
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": false,
    "context": {
      "blocked_by": "registry",
      "detail": "Awaiting registry confirmation. This may take up to 24 hours.",
      "domain_name": "example.com"
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "blocked",
    "updated_at": "2025-10-27T10:05:00Z"
  },
  "success": true
}
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": true,
    "context": {
      "domain_name": "example.com"
    },
    "created_at": "2025-10-27T10:00:00Z",
    "error": {
      "code": "registry_rejected",
      "message": "Registry rejected the registration request."
    },
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "failed",
    "updated_at": "2025-10-27T10:00:08Z"
  },
  "success": true
}
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": false,
    "context": {
      "domain_name": "example.com"
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "in_progress",
    "updated_at": "2025-10-27T10:00:12Z"
  },
  "success": true
}
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": true,
    "context": {
      "domain_name": "example.com",
      "registration": {
        "auto_renew": true,
        "created_at": "2025-10-27T10:00:00Z",
        "domain_name": "example.com",
        "expires_at": "2026-10-27T10:00:00Z",
        "locked": true,
        "privacy_mode": "redaction",
        "status": "active"
      }
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "succeeded",
    "updated_at": "2025-10-27T10:00:03Z"
  },
  "success": true
}
{
  "errors": [
    {
      "code": 10000,
      "message": "No workflow found for example.com"
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}
Returns Examples
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": false,
    "context": {
      "action": "registrant_email_confirmation_pending",
      "confirmation_sent_to": "a***@example.com",
      "domain_name": "example.com"
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "action_required",
    "updated_at": "2025-10-27T10:01:00Z"
  },
  "success": true
}
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": false,
    "context": {
      "blocked_by": "registry",
      "detail": "Awaiting registry confirmation. This may take up to 24 hours.",
      "domain_name": "example.com"
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "blocked",
    "updated_at": "2025-10-27T10:05:00Z"
  },
  "success": true
}
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": true,
    "context": {
      "domain_name": "example.com"
    },
    "created_at": "2025-10-27T10:00:00Z",
    "error": {
      "code": "registry_rejected",
      "message": "Registry rejected the registration request."
    },
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "failed",
    "updated_at": "2025-10-27T10:00:08Z"
  },
  "success": true
}
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": false,
    "context": {
      "domain_name": "example.com"
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "in_progress",
    "updated_at": "2025-10-27T10:00:12Z"
  },
  "success": true
}
{
  "errors": [],
  "messages": [],
  "result": {
    "completed": true,
    "context": {
      "domain_name": "example.com",
      "registration": {
        "auto_renew": true,
        "created_at": "2025-10-27T10:00:00Z",
        "domain_name": "example.com",
        "expires_at": "2026-10-27T10:00:00Z",
        "locked": true,
        "privacy_mode": "redaction",
        "status": "active"
      }
    },
    "created_at": "2025-10-27T10:00:00Z",
    "links": {
      "resource": "/accounts/abc/registrar/registrations/example.com",
      "self": "/accounts/abc/registrar/registrations/example.com/registration-status"
    },
    "state": "succeeded",
    "updated_at": "2025-10-27T10:00:03Z"
  },
  "success": true
}
{
  "errors": [
    {
      "code": 10000,
      "message": "No workflow found for example.com"
    }
  ],
  "messages": [],
  "result": null,
  "success": false
}