In Cloudflare Workers, what counts as a subrequest, and how many can one invocation make on each plan?
answer
- outbound calls, not incoming ones
- bindings count too
- every redirect hop
- limits.subrequests
- six waiting for headers
basics
~20 sA subrequest is any outbound fetch() or binding call to a Cloudflare service such as KV, R2 or D1, and each redirect hop counts. Free allows 50 external and 1,000 Cloudflare-service subrequests per invocation; Paid defaults to 10,000, settable to 10 million.
solid answer
~40 sA **subrequest** is any request a Worker makes during an invocation: a `fetch()` to the internet, or a call through a binding to a Cloudflare service such as KV, R2 or D1. Each hop of a redirect chain is a separate subrequest, so the count can exceed the number of `fetch()` calls in the code. Workers Free allows 50 external subrequests and 1,000 to Cloudflare services per invocation. Workers Paid defaults to 10,000, and `limits.subrequests` in the Wrangler file can raise that to 10 million or lower it as a guard. Separately, at most six connections per invocation may be waiting for response headers at once; a seventh is queued, not failed.
code
json · 8 lines{
"name": "image-metadata",
"main": "src/index.js",
"compatibility_date": "2026-10-01",
"limits": {
"subrequests": 2000
}
}go deeper
Recall what a subrequest is, outbound fetch() and binding calls, and the headline limits: 50 external on Free, 10,000 by default on Paid.
Explain why redirects and binding calls inflate the count, how limits.subrequests raises or lowers it, and how the six-connections-waiting rule queues rather than fails.
Size fan-out designs against both limits: count redirects, batch large lists, keep a guard limit for runaway loops, and expect pending calls to run six at a time.
Set guard limits as a team default: low subrequest and CPU caps on Workers that never need more, with documented exceptions for long-lived or fan-out Workers.
## What a subrequest is A Cloudflare Worker is invoked by an incoming event, usually an HTTP request. Anything the Worker sends out while handling that event is a **subrequest**: - a `fetch()` call to any URL, including the origin behind the Worker; - a call through a binding to a Cloudflare service, such as `env.KV.get()`, an R2 `put()`, or a D1 query; - every hop of a redirect chain that `fetch()` follows automatically. The redirect rule surprises people. With the default redirect handling, a `fetch()` that receives two `301` responses before the final `200` has made three requests, and all three count. That is why the documentation warns that the total number of subrequests may exceed the number of `fetch()` calls in the code. ## The limits by plan | Limit per invocation | Workers Free | Workers Paid | |---|---|---| | External subrequests | 50 | 10,000 by default, up to 10,000,000 | | Subrequests to Cloudflare services | 1,000 | same as the configured limit | | Connections waiting for response headers at once | 6 | 6 | There is no time limit on an individual subrequest: as long as the client stays connected, the Worker can keep making them. Once the response is complete or the client disconnects, outstanding work may be cancelled unless it was handed to `ctx.waitUntil()`. ## Changing the limit with `limits.subrequests` Workers Paid sets the limit per Worker with the `limits` block of the Wrangler configuration file: ```json { "limits": { "subrequests": 2000 } } ``` The key works in both directions: 1. **Raise it** for long-lived invocations that legitimately make many calls, such as a long-lived WebSocket on a Durable Object or a long-running Workflow. 2. **Lower it** to cap runaway code, for instance a pagination loop that never sees its stop condition, before it fans out into thousands of billed calls. Like `limits.cpu_ms`, the setting is enforced on Cloudflare's network, not in local `wrangler dev`. ## The separate six-connection rule The subrequest limit counts *how many* calls an invocation makes. A second, unrelated limit counts *how many are pending at once*: each invocation can have at most six connections that have not yet received response headers. This covers `fetch()`, the KV `get()`, `put()`, `list()` and `delete()` methods, R2's object methods, the Cache API's `put()`, `match()` and `delete()`, Queues `send()` and `sendBatch()`, and opening a TCP socket with `connect()`. Outbound WebSockets count too. When a seventh connection starts while six are still waiting, it is **queued** until one of them receives its headers. Nothing fails, but a Worker that launches 200 `fetch()` calls with `Promise.all()` runs them about six at a time. Once headers arrive, the connection stops counting even while its body streams, and calling `response.body.cancel()` on a body you do not need frees memory. ## Counting a real invocation Suppose the image-metadata Worker receives a list of 100 image URLs, fetches each one, and writes one KV entry per image. Ten of the URLs answer with a single redirect before the image. The invocation spends: - 100 `fetch()` calls plus 10 followed redirect hops, so 110 external subrequests; - 100 KV writes, which are subrequests to a Cloudflare service. On Workers Free the external count of 110 is over the limit of 50, so the invocation runs out of external subrequests before it finishes, even though the 100 KV writes fit easily under 1,000. On Workers Paid all 210 subrequests sit far below the 10,000 default. ## Designing within the limit Take the image-metadata Worker receiving a JSON list of image URLs and fetching each one to read its headers: - On Workers Free, a list longer than 50 entries cannot be handled in one invocation; batch the list or move the fan-out to a background consumer. - On Workers Paid, a 5,000-image list fits under the default, but redirects on each image URL can double the count; decide whether to follow redirects at all. - Expect at most six requests waiting on headers at once, and size the work so a request's wall time stays acceptable. - Set `limits.subrequests` to the largest number the design can justify, so a bug fails fast instead of spending.
- Why might a Worker exhaust its subrequest limit with fewer fetch() calls in its code than the limit?Because more than `fetch()` counts. Every hop of a followed redirect is its own subrequest, and calls through bindings to KV, R2, D1 and other Cloudflare services count as well. A loop that does one `fetch()` and one KV write per item spends two subrequests per item, more if the URLs redirect.
- How is the six-connection rule different from the subrequest limit?The subrequest limit caps the total number of calls in an invocation; exceeding it fails the call. The six-connection rule caps how many calls may be waiting for response headers at the same moment; a seventh is queued until one receives its headers. One limits volume, the other concurrency.
- Calls through KV, R2 or D1 bindings never count as subrequests.
- A fetch() counts once however many redirects it follows.
- Workers Paid is hard-capped at 1,000 subrequests per invocation.
- A seventh concurrent fetch() fails because only six connections are allowed.
- limits.subrequests can only raise the limit, never lower it.
Assumes Workers limits as of 2026-10-10: since 2026-02-11 Workers Paid defaults to 10,000 subrequests per invocation, settable with limits.subrequests; before that the cap was 1,000.