1# Smart Placement API
2 
3## Placement Status API
4 
5Query Worker placement status via Cloudflare API:
6 
7```bash
8curl -X GET "https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/workers/services/{WORKER_NAME}" \
9  -H "Authorization: Bearer <TOKEN>" \
10  -H "Content-Type: application/json"
11```
12 
13Response includes `placement_status` field:
14 
15```typescript
16type PlacementStatus = 
17  | undefined  // Not yet analyzed
18  | 'SUCCESS'  // Successfully optimized
19  | 'INSUFFICIENT_INVOCATIONS'  // Not enough traffic
20  | 'UNSUPPORTED_APPLICATION';  // Made Worker slower (reverted)
21```
22 
23## Status Meanings
24 
25**`undefined` (not present)**
26- Worker not yet analyzed
27- Always runs at default edge location closest to user
28 
29**`SUCCESS`**
30- Analysis complete, Smart Placement active
31- Worker runs in optimal location (may be edge or remote)
32 
33**`INSUFFICIENT_INVOCATIONS`**
34- Not enough requests to make placement decision
35- Requires consistent multi-region traffic
36- Always runs at default edge location
37 
38**`UNSUPPORTED_APPLICATION`** (rare, <1% of Workers)
39- Smart Placement made Worker slower
40- Placement decision reverted
41- Always runs at edge location
42- Won't be re-analyzed until redeployed
43 
44## cf-placement Header (Beta)
45 
46Smart Placement adds response header indicating routing decision:
47 
48```typescript
49// Remote placement (Smart Placement routed request)
50"cf-placement: remote-LHR"  // Routed to London
51 
52// Local placement (default edge routing)  
53"cf-placement: local-EWR"   // Stayed at Newark edge
54```
55 
56Format: `{placement-type}-{IATA-code}`
57- `remote-*` = Smart Placement routed to remote location
58- `local-*` = Stayed at default edge location
59- IATA code = nearest airport to data center
60 
61**Warning:** Beta feature, may be removed before GA.
62 
63## Detecting Smart Placement in Code
64 
65**Note:** `cf-placement` header is a beta feature and may change or be removed.
66 
67```typescript
68export default {
69  async fetch(request: Request, env: Env): Promise<Response> {
70    const placementHeader = request.headers.get('cf-placement');
71    
72    if (placementHeader?.startsWith('remote-')) {
73      const location = placementHeader.split('-')[1];
74      console.log(`Smart Placement routed to ${location}`);
75    } else if (placementHeader?.startsWith('local-')) {
76      const location = placementHeader.split('-')[1];
77      console.log(`Running at edge location ${location}`);
78    }
79    
80    return new Response('OK');
81  }
82} satisfies ExportedHandler<Env>;
83```
84 
85## Request Duration Metrics
86 
87Available in Cloudflare dashboard when Smart Placement enabled:
88 
89**Workers & Pages → [Your Worker] → Metrics → Request Duration**
90 
91Shows histogram comparing:
92- Request duration WITH Smart Placement (99% of traffic)
93- Request duration WITHOUT Smart Placement (1% baseline)
94 
95**Request Duration vs Execution Duration:**
96- **Request duration:** Total time from request arrival to response delivery (includes network latency)
97- **Execution duration:** Time Worker code actively executing (excludes network waits)
98 
99Use request duration to measure Smart Placement impact.
100 
101### Interpreting Metrics
102 
103| Metric Comparison | Interpretation | Action |
104|-------------------|----------------|--------|
105| WITH < WITHOUT | Smart Placement helping | Keep enabled |
106| WITH ≈ WITHOUT | Neutral impact | Consider disabling to free resources |
107| WITH > WITHOUT | Smart Placement hurting | Disable with `mode: "off"` |
108 
109**Why Smart Placement might hurt performance:**
110- Worker primarily serves static assets or cached content
111- Backend services are globally distributed (no single optimal location)
112- Worker has minimal backend communication
113- Using Pages with `assets.run_worker_first = true`
114 
115**Typical improvements when Smart Placement helps:**
116- 20-50% reduction in request duration for database-heavy Workers
117- 30-60% reduction for Workers making multiple backend API calls
118- Larger improvements when backend is geographically concentrated
119 
120## Monitoring Commands
121 
122```bash
123# Tail Worker logs
124wrangler tail your-worker-name
125 
126# Tail with filters
127wrangler tail your-worker-name --status error
128wrangler tail your-worker-name --header cf-placement
129 
130# Check placement status via API
131curl -H "Authorization: Bearer $TOKEN" \
132  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
133  | jq .result.placement_status
134```
135 
136## TypeScript Types
137 
138```typescript
139// Placement status returned by API (field may be absent)
140type PlacementStatus = 
141  | 'SUCCESS'
142  | 'INSUFFICIENT_INVOCATIONS'
143  | 'UNSUPPORTED_APPLICATION'
144  | undefined;
145 
146// Placement configuration in wrangler.jsonc
147type PlacementMode = 'smart' | 'off';
148 
149interface PlacementConfig {
150  mode: PlacementMode;
151  // Legacy fields (deprecated/removed):
152  // hint?: string;  // REMOVED - no longer supported
153}
154 
155// Explicit placement (separate feature from Smart Placement)
156interface ExplicitPlacementConfig {
157  region?: string;
158  host?: string;
159  hostname?: string;
160  // Cannot combine with mode field
161}
162 
163// Worker metadata from API response
164interface WorkerMetadata {
165  placement?: PlacementConfig | ExplicitPlacementConfig;
166  placement_status?: PlacementStatus;
167}
168 
169// Service Binding for backend Worker
170interface Env {
171  BACKEND_SERVICE: Fetcher;  // Service Binding to backend Worker
172  DATABASE: D1Database;
173}
174 
175// Example Worker with Service Binding
176export default {
177  async fetch(request: Request, env: Env): Promise<Response> {
178    // Forward to backend Worker with Smart Placement enabled
179    const response = await env.BACKEND_SERVICE.fetch(request);
180    return response;
181  }
182} satisfies ExportedHandler<Env>;
183```
184