Placement (2)

Last updated Oct 12, 2026 By default, Workers and Pages Functions run in a data center closest to where the request was received. If your Worker makes requests to back-end infrastructure such as databases or APIs, it may be more performant to run that Worker closer to your back-end than the end user.

{
    "placement": {
        // Use one of the following options (mutually exclusive):
        "mode": "smart", // Cloudflare automatically places your Worker closest to the upstream with the most requests
        "region": "gcp:us-east4", // Explicit cloud region to run your Worker closest to - e.g. "gcp:us-east4" or "aws:us-east-1"
        "host": "db.example.com:5432", // A host to probe (TCP/layer 4) - e.g. a database host - and place your Worker closest to
        "hostname": "api.example.com", // A hostname to probe (HTTP/layer 7) - e.g. an API endpoint - and place your Worker closest to
    },
}

[placement]
mode = "smart"
region = "gcp:us-east4"
host = "db.example.com:5432"
hostname = "api.example.com"

Placement can reduce the overall latency of a Worker request by minimizing roundtrip latency of requests between your Worker and back-end services. You can achieve single-digit millisecond latency to databases, APIs, and other services running in legacy cloud infrastructure.

Understand placement

Consider a user in Sydney, Australia accessing an application running on Workers. This application makes multiple round trips to a database in Frankfurt, Germany.

The latency from multiple round trips between Sydney and Frankfurt adds up. By placing the Worker near the database, Cloudflare reduces the total request duration.

Enable Smart Placement

Smart Placement automatically analyzes your Worker's traffic patterns and places it in an optimal location. Use Smart Placement when:

• Your Worker connects to multiple back-end services
• You do not know the exact location of your infrastructure
• Your back-end services are distributed or replicated

Smart Placement is enabled on a per-Worker basis. Once enabled, it analyzes the request duration of the Worker in different Cloudflare locations on a regular basis.

For each candidate location, Smart Placement considers the Worker's performance and the network latency added by forwarding the request. If a candidate location is significantly faster, the request is forwarded there. Otherwise, the Worker runs in the default location closest to the request.

Smart Placement only considers locations where the Worker has previously run. It cannot place your Worker in a location that does not normally receive traffic.

Review limitations

• Smart Placement only affects the execution of fetch event handlers. It does not affect RPC methods or named entrypoints.
• Workers without a fetch event handler are ignored by Smart Placement.
• Static assets are always served from the location nearest to the incoming request. If your code retrieves assets via the static assets binding, assets are served from the location where your Worker runs.

Enable smart placement

Smart Placement is available on all Workers plans.

Configure with Wrangler

Add the following to your Wrangler configuration file:

{
    "placement": {
        "mode": "smart",
    },
}

[placement]
mode = "smart"

Smart Placement may take up to 15 minutes to analyze your Worker after deployment.

Configure in the dashboard

1. Go to Workers & Pages. Go to Workers & Pages ↗
2. Select your Worker.
3. Go to Settings > General.
4. Under Placement, select Smart.

Smart Placement requires consistent traffic to the Worker from multiple locations to make a placement decision. The analysis process may take up to 15 minutes.

Check placement status

Query your Worker's placement status through the Workers API:

curl -X GET https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
-H "Content-Type: application/json" | jq .

Possible placement states:

Review request duration analytics

Once Smart Placement is enabled, data about request duration is collected. Request duration is measured at the data center closest to the end user. By default, 1% of requests are not routed with Smart Placement to serve as a baseline for comparison.

View your Worker's request duration analytics to measure the impact of Smart Placement.

Check the cf-placement header

Cloudflare adds a cf-placement header to all requests when placement is enabled. Use this header to check whether a request was routed with Smart Placement and where the Worker processed the request.

The header value includes a placement type and an airport code indicating the data center location:

• remote-LHR — The request was routed using Smart Placement to a data center near London.
• local-EWR — The request was not routed using Smart Placement. The Worker ran in the default location near Newark.

Caution

The cf-placement header may be removed before Smart Placement exits beta.

Configure explicit Placement Hints

Placement Hints let you explicitly specify where your Worker runs. Use Placement Hints when:

• You know the exact location of your back-end infrastructure
• Your Worker connects to a single database, API, or service
• Your infrastructure is single-homed (not replicated or anycasted)

Examples include a primary database, a virtual machine, or a Kubernetes cluster in a specific region. Reducing round-trip latency from 20 to 30 milliseconds per query to 1 to 3 milliseconds improves response times.

Note

Workers run on Cloudflare's global network ↗︎, not inside cloud provider regions. Placement Hints run your Worker in the data center with the lowest latency to your specified cloud region. At extremely high request volumes (hundreds of thousands of requests per second or more), Cloudflare may run instances across a more distributed area to balance traffic.

Specify a cloud region

If your infrastructure runs in AWS, GCP, or Azure, set the placement.region property using the format {provider}:{region}:

{
    "placement": {
        "region": "aws:us-east-1", // Explicit cloud region to run your Worker closest to - e.g. "gcp:us-east4" or "aws:us-east-1"
    },
}

[placement]
region = "aws:us-east-1"

Cloudflare maps your specified cloud region to the data center with the lowest latency to that region. Cloudflare automatically adjusts placement to account for network maintenance or changes, so you do not need to specify failover regions.

Specify a host endpoint

If your infrastructure is not in a major cloud provider, you can specify an endpoint for Cloudflare to probe. Cloudflare will triangulate the position of your external host and place Workers in a nearby region.

Note

Host-based placement is experimental.

Set placement.host to identify a layer 4 service. Cloudflare uses TCP CONNECT checks to measure latency and selects the best data center.

{
    "placement": {
        "host": "my_database_host.com:5432", // A host to probe (TCP/layer 4) - e.g. a database host - and place your Worker closest to
    },
}

[placement]
host = "my_database_host.com:5432"

Set placement.hostname to identify a layer 7 service. Cloudflare uses HTTP HEAD checks to measure latency and selects the best data center.

{
    "placement": {
        "hostname": "my_api_server.com", // A hostname to probe (HTTP/layer 7) - e.g. an API endpoint - and place your Worker closest to
    },
}

[placement]
hostname = "my_api_server.com"

Probes are sent from public IP ranges, not Cloudflare IP ranges. Cloudflare rechecks service location at regular intervals. These probes locate single-homed resources and do not work correctly for broadcast, anycast, multicast, or replicated resources.