BudiBadu Logo
Samplebadu

cURL by Example: HEAD Request

Latest

Fetch headers only. This is useful for checking if a resource exists or inspecting metadata without downloading the body.

Code

# Fetch headers only
curl -I https://example.com

# Also works with -L to see redirect chain headers
curl -IL https://example.com

# Combine with other flags
curl -I -H "Authorization: Bearer token" https://api.example.com/resource

Explanation

A HEAD request is an HTTP method that is functionally identical to a GET request, except that the server's response does not include the message body—only the HTTP headers are returned. This makes HEAD requests extremely efficient for retrieving metadata about a resource without consuming bandwidth by downloading its entire content. The -I flag (or its long form --head) instructs cURL to send an HTTP HEAD request to the specified URL and display only the response headers.

Why Use HEAD Requests? HEAD requests serve several critical purposes in web development and system administration: Checking Resource Availability - quickly determine if a server is live and if a specific resource exists (checking for 200 OK vs 404 Not Found) without downloading the content, which is invaluable for monitoring and health checks; Retrieving Metadata - obtain crucial information such as the HTTP status code, Content-Type (file format), Content-Length (file size in bytes), Last-Modified date (when the resource was last updated), ETag (entity tag for cache validation), and various caching headers like Cache-Control and Expires; Verifying Server Configuration - inspect caching policies, redirection information (Location headers), security headers (CORS, CSP, HSTS), and other server-side configurations without fetching actual content; Debugging and API Testing - developers and system administrators use HEAD requests to debug web applications, test API endpoints, verify security settings, and understand how servers will respond before committing to a full GET request.

How HEAD Differs from GET: While semantically similar, HEAD requests tell the server "give me everything you would send for a GET request, but omit the body." This means all headers, status codes, and metadata are identical to what a GET would return, but the actual content (HTML, JSON, file data, etc.) is never transmitted. This is particularly useful when you need to check if a large file exists or has been modified without actually downloading it. Be aware that some poorly implemented servers or applications might not handle HEAD requests correctly, sometimes returning different headers than they would for GET, or even rejecting HEAD requests entirely—though this violates HTTP specifications.

Practical Applications: When combined with -L, the HEAD request will follow redirects and show you headers for each step in the redirect chain, which is excellent for debugging redirect loops or understanding redirect paths. You can combine -I with authentication headers, custom headers, or any other cURL flag to test authenticated endpoints or APIs. For example, checking if a resource in a CDN has been purged, verifying correct cache headers are being sent, testing if CORS headers are configured properly, or monitoring when a webpage was last modified for change detection systems. The bandwidth savings can be substantial—checking a 1GB file for existence or modification uses only a few kilobytes with HEAD versus downloading the entire gigabyte with GET.

Code Breakdown

2
-I sends a HEAD request, fetching only headers without the response body.
5
-IL combines HEAD request with following redirects, showing headers for each hop.