Asynchronous DNS operations return a task or job reference so you can follow work after the HTTP request finishes. Keep that reference with your business operation and request ID. A queued response means the server accepted work; it does not mean a website, mail route or public resolver has already changed.
| Method | Resource | Scope | Idempotency-Key |
|---|---|---|---|
GET |
/v2/dns/tasks |
dns:read |
Not required by this route |
GET |
/v2/dns/tasks/{taskId} |
dns:read |
Not required by this route |
01 Track the right resource
- Store the identifier returned by the initiating operation, such as a backup, migration, DNSSEC request or secondary refresh.
- Read that task directly. Inspect the job's state, result and failure details together with any associated DNS tasks.
- When using the collection, follow pagination and filter by the relevant resource or job type in your application. This handler lists tenant jobs, not exclusively DNS jobs.
- Use a bounded polling interval and respect rate-limit or retry information. Stop polling when the operation reaches a terminal state or your support workflow takes over.
- After completion, verify the resulting resource and authoritative DNS answers. Record that verification separately from task completion.
02 Handle partial and delayed outcomes
The task detail response embeds a maximum of 50 DNS task rows. Do not present that array as a complete large deployment report. Keep the initiating operation's own result, changeset references and provider evidence, and use the applicable management screens or support process when a complete child-task history is needed.
If work is pending, inspect worker and provider availability through the administrator's workflow. Repeatedly resubmitting the original mutation with new idempotency keys can create competing work. Recover an uncertain HTTP result with the original key and payload, then follow the returned operation.
Common questions
Why does a completed job still show old DNS in my browser?
The browser or recursive resolver may hold a cached answer, or the domain may delegate elsewhere. Query the intended authoritative nameserver directly and compare the public parent delegation before blaming the completed job.
Is every failed task safe to retry?
No. Read the error and the recorded side effects. Some failures require corrected permissions, a fresh preview or reconciliation of work that already reached the provider.
What should an integration show the customer?
Use clear states such as submitted, processing, needs attention and verified, derived from actual evidence. Include a support reference while withholding credentials, internal secrets and unrelated tenant details.