Response Headers

Fetch any URL and return its HTTP status and response headers as JSON.

API ReferenceCopy Anchor Link

GET /headersCopy Anchor Link

Uses HEAD first and falls back to GET when the origin does not support HEAD.

Example RequestCopy Anchor Link

curl "https://your-worker.workers.dev/headers?url=https://www.cloudflare.com"

Success ResponseCopy Anchor Link

url string

Final URL after redirects

statusCode number

HTTP status code

statusText string

HTTP status text

method string

HEAD or GET

headers object

Response headers as key/value pairs

{
  "url": "https://www.cloudflare.com/",
  "statusCode": 200,
  "statusText": "OK",
  "method": "HEAD",
  "headers": {
    "content-type": "text/html; charset=utf-8",
    "server": "cloudflare"
  }
}

Error CodesCopy Anchor Link

• 400 - Missing or invalid url (INVALID_URL)
• 502 - Fetch failed (FETCH_ERROR)

Use CasesCopy Anchor Link

• Debug cache and security headers from the edge
• Compare response headers across origins
• Learn HEAD vs GET fallback patterns in Workers

LimitationsCopy Anchor Link

• Uses HEAD with GET fallback; some origins return different headers per method
• Single URL per request
• Fetch timeout on slow origins

Use in your projectCopy Anchor Link

import { USER_AGENT } from "../constants/defaults";import type { HeadersResponse } from "../types/headers";import { headersToRecord, shouldRetryWithGet } from "./url";async function fetchWithMethod(url: string, method: "HEAD" | "GET"): Promise<Response> {  return fetch(url, {    method,    redirect: "follow",    headers: { "User-Agent": USER_AGENT },  });}export async function inspectResponseHeaders(url: string): Promise<HeadersResponse> {  let method: "HEAD" | "GET" = "HEAD";  let response = await fetchWithMethod(url, method);  if (shouldRetryWithGet(response.status)) {    method = "GET";    response = await fetchWithMethod(url, method);  }  return {    url: response.url,    statusCode: response.status,    statusText: response.statusText,    method,    headers: headersToRecord(response.headers),  };}

DeploymentCopy Anchor Link

curl "https://your-worker.workers.dev/headers?url=https://www.cloudflare.com"

Local DevelopmentCopy Anchor Link

cd apps/experiments/response-headers
npm install
npm run dev

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• Fetch API - HTTP requests from the edge