Cloudflare Docs
Visit Workers on GitHub
Set theme to dark (⇧+D)


​​ Background

Routes allow users to map a URL pattern to a Worker script to enable Workers to run in front of Custom Domains or their own application servers.

​​ Customize your routes

For zones proxied on Cloudflare, route patterns decide what (if any) script is matched based on the URL of that request. Requests are routed through a Workers script when the URL matches a route pattern assigned to that script. To add a Route, you need:

  1. An active Cloudflare zone.
  2. A proxied (orange-clouded) DNS record.
  3. A Worker to invoke.

Route patterns can be added with the Cloudflare API or in Account Home > Workers > your Worker > Triggers > Add route in the Cloudflare dashboard.

Cloudflare Site routes are comprised of:

The Routes REST API documentation can be found in the Workers API docs.

If your route is configured to a hostname, you will need to add a DNS record to Cloudflare to ensure that the hostname can be resolved externally. If your Worker acts as your origin (that is, the request terminates in a Worker), you must add a DNS record.

​​ Routes with *

Cloudflare Workers accounts come with a * subdomain that is configurable in the Cloudflare dashboard. Your * subdomain allows you to deploy Workers without attaching your domain as a Cloudflare zone.

To claim a * subdomain, such as <YOUR_SUBDOMAIN>, go to Account Home > Workers > Your subdomain. The name field in your Worker configuration is used as the preview subdomain for the deployed script, (for example, my-worker.<YOUR_SUBDOMAIN>

​​ Matching Behavior

Route patterns look like this:


This pattern would match all HTTPS requests destined for a subhost of and whose paths are prefixed by /images/.

A pattern to match all requests looks like this:


While they look similar to a regex pattern, route patterns follow specific rules:

  • The only supported operator is the wildcard (*), which matches zero or more of any character.

  • Route patterns may not contain infix wildcards or query parameters. For example, neither*.jpg nor* are valid route patterns.

  • When more than one route pattern could match a request URL, the most specific route pattern wins. For example, the pattern* would take precedence over ** when matching a request for The pattern* would take precedence over* when matching a request for

  • Route pattern matching considers the entire request URL, including the query parameter string. Since route patterns may not contain query parameters, the only way to have a route pattern match URLs with query parameters is to terminate it with a wildcard, *.

  • Route patterns are case sensitive, for example,* and* are two distinct routes.

A route can be specified without being associated with a Worker. This will act to negate any less specific patterns. For example, consider this pair of route patterns, one with a Workers script and one without:

* -> <no script>
** -> worker-script

In this example, all requests destined for and whose paths are prefixed by /images/ would be routed to worker-script, except for /images/cat.png, which would bypass Workers completely. Requests with a path of /images/cat.png?foo=bar would be routed to worker-script, due to the presence of the query string.

​​ Configure your wrangler.toml

To configure a route in your wrangler.toml, add the following to your environment:

routes = [
{ pattern = "", zone_id = "<YOUR_ZONE_ID>" }

If you have specified your zone ID in the environment of your wrangler.toml, you will not need to write it again in object form.

​​ Validity

The following set of rules govern route pattern validity.

​​ Route patterns must include your zone

If your zone is, then the simplest possible route pattern you can have is, which would match and, and nothing else. As with a URL, there is an implied path of / if you do not specify one.

​​ Route patterns may not contain any query parameters

For example, is not a valid route pattern.

​​ Route patterns may optionally begin with http:// or https://

If you omit a scheme in your route pattern, it will match both http:// and https:// URLs. If you include http:// or https://, it will only match HTTP or HTTPS requests, respectively.

  • https://* matches but not

  • * matches both and

​​ Hostnames may optionally begin with *

If a route pattern hostname begins with *, then it matches the host and all subhosts. If a route pattern hostname begins with *., then it only matches all subhosts.

  • * matches and

  • * matches but not

​​ Paths may optionally end with *

If a route pattern path ends with *, then it matches all suffixes of that path.

  •* matches and and

​​ Subdomains must have a DNS Record

All subdomains must have a DNS record to be proxied on Cloudflare and used to invoke a Worker. For example, if you want to put a worker on, and you have added to Cloudflare but have not added any DNS records for, any request to will result in the error ERR_NAME_NOT_RESOLVED.