The /dns_records/batch endpoint is available to every Cloudflare zone. Free tier accounts can submit 200 changes in a single batch; paid plans can submit 3,500. Testing has been carried out successfully with as many as 100,000 changes in one call. Clients send a POST request carrying a JSON object in the body, structured as follows:

{
    deletes:[]Record
    patches:[]Record
    puts:[]Record
    posts:[]Record
}

Every []Record list follows the same requirements as the regular API, with one difference: for deletes, patches and puts the record ID must be supplied inside the Record object. A minimal example:

{
    "deletes": [
        {
            "id": "143004ef463b464a504bde5a5be9f94a"
        },
        {
            "id": "165e9ef6f325460c9ca0eca6170a7a23"
        }
    ],
    "patches": [
        {
            "id": "16ac0161141a4e62a79c50e0341de5c6",
            "content": "192.0.2.45"
        },
        {
            "id": "6c929ea329514731bcd8384dd05e3a55",
            "name": "update.example.com",
            "proxied": true
        }
    ],
    "puts": [
        {
            "id": "ee93eec55e9e45f4ae3cb6941ffd6064",
            "content": "192.0.2.50",
            "name": "no-change.example.com",
            "proxied": false,
            "ttl:": 1
        },
        {
            "id": "eab237b5a67e41319159660bc6cfd80b",
            "content": "192.0.2.45",
            "name": "no-change.example.com",
            "proxied": false,
            "ttl:": 3000
        }
    ],
    "posts": [
        {
            "name": "@",
            "type": "A",
            "content": "192.0.2.45",
            "proxied": false,
            "ttl": 3000
        },
        {
            "name": "a.example.com",
            "type": "A",
            "content": "192.0.2.45",
            "proxied": true
        }
    ]
}

Execution order and failure semantics

The API parses the payload and runs the calls in a fixed sequence: deletes, then patches, then puts, then posts. Within each list, records are processed in the order given. That ordering removes conflict handling from the client's side — for instance, it becomes possible to create a CNAME on a hostname that still holds a to-be-deleted A record, a combination RFC 1912 disallows.

The batch is atomic at the database layer: the whole request runs inside a single transaction, so if any individual action fails, everything rolls back and the API returns the first error encountered. Responses mirror the request format, and patches or puts that produce no actual change are placed at the end of their respective lists.

Atomicity does not extend to the edge. After a successful commit, changes propagate to Cloudflare's edge through Quicksilver, the distributed KV store, where each record change is a separate key-value pair and database transactions are not supported. Propagation to edge servers is therefore not guaranteed to be atomic. If, for example, a delegation is being replaced by an A record, some resolvers may observe the NS record disappear before the A record appears.

Dashboard controls

The Cloudflare dashboard gains multi-record selection, after which users can:

  1. Delete all selected records
  2. Change the proxy status of all selected records
BLOG-2495 2

Further batch actions in the dashboard will follow based on user feedback.

What the batch endpoint sits on

The endpoint caps a multi-year, multi-team effort to speed up the DNS pipeline that carries customer records into Quicksilver. The DNS Records API is Cloudflare's most heavily used public API, peaking at twice the request volume of any other, and it backs more than 20 internal services, including DNSSEC, TLS, Email, Tunnels, Workers, Spectrum and R2 storage — which made scalability a hard requirement.

Improving performance began with understanding the stack. Cloudflare uses Jaeger tracing for debugging, which exposes granular detail for a sample of incoming requests. In request latency traces, the standout span was time spent on individual database lookups, ranging from roughly 1ms to 5ms.

BLOG-2495 3
BLOG-2495 4

Jaeger trace showing variable database latency

To find out what happened inside each request, the team tabulated database lookups per action:

Action

Database Queries

Reason

POST

2 

One to write and one to read the new record.

PUT

3

One to collect, one to write, and one to read back the new record.

PATCH

3

One to collect, one to write, and one to read back the new record.

DELETE

2

One to read and one to delete.

Reads after POST, PUT and PATCH were necessary because database-filled fields on the record cannot be inferred in the API. The cost adds up: editing 1,000 records at 3ms per lookup meant 3ms × 3 lookups × 1,000 records = 9 seconds of database time alone, before API round trips and other processing. The goal became fewer queries and less variation in per-query latency.

On variation: none of these calls is a plain INSERT, UPDATE or DELETE, since sanitization functions wrap each database call. To see where the time went, the team enabled PostgreSQL's auto_explain with these settings:

BLOG-2495 5

A subset of queries showed durations ten times longer than others:

BLOG-2495 6

Several code paths ran queries of the form:

IF (EXISTS (SELECT id FROM table WHERE row_hash = __new_row_hash))

For inserts into very large zones, such patterns could stretch query times further, plausibly explaining the 1ms–5ms spread seen in tracing. Investigation showed a unique index already existed on exactly that hash, so the existence checks could be removed without risking duplicate rows.

Next came database batching. In any API, external calls such as SQL queries add substantial latency, and batching lets the DNS Records API execute multiple SQL queries in one network call, cutting the number of database round trips. Each write had also been followed by a read to collect values such as creation/modification timestamps and new IDs; the database functions were changed to return the newly created DNS record directly, eliminating a full round trip. The revised lookup table:

Action

Database Queries

Reason

POST

1 

One to write

PUT

2

One to read, one to write.

PATCH

2

One to read, one to write.

DELETE

2

One to read, one to delete.

Further reduction is constrained by auditing and other sanitization logic.

Results:

Action

Average database time before

Average database time after

Percentage Decrease

POST

3.38ms

0.967ms

71.4%

PUT

4.47ms

2.31ms

48.4%

PATCH

4.41ms

2.24ms

49.3%

DELETE

1.21ms

1.21ms

0%

Besides lowering API latency, this cut database query load, which benefits other systems as well.

The API itself can only go so far: every record it accepts still has to be processed and written to Quicksilver, Cloudflare's distributed configuration database. At volumes where customers create tens of thousands of records every 10 seconds, the downstream path becomes the limiting factor unless the writes are consolidated before they reach the database.

A May 2022 post on improving DNS record build speed by more than 4,000x flagged this as forthcoming work:

We plan to introduce a batching system that will collect record changes into groups to minimize the number of queries we make to our database and Quicksilver.

That work is now complete. The propagation pipeline collects thousands of record changes into a single database query, which is then published to Quicksilver for distribution across the global network.

What's still in the works

Further API improvements are under consideration. On the UI side, the plan is to add usability improvements that make zone management in the dashboard easier. Feedback on either front is invited through the linked research panel.

Usage details for the /batch endpoint are documented in the developer documentation and the API reference for batching DNS records in a zone.