How to Use cURL HEAD Requests: A Developer’s Guide - ApyHub
apyhub-logo
PlatformAPI CatalogPricingBlog
Engineering

How to Use cURL HEAD Requests: A Developer’s Guide

Learn curl HEAD requests to verify resources, save bandwidth, and grab metadata fast. This guide offers commands, examples, and advanced tips for developers.
How to Use cURL HEAD Requests: A Developer’s Guide
SO
Sohail Pathan
Last updated on March 14, 2025
When you need to check if a webpage or resource exists without downloading its full content, cURL HEAD requests are your go-to tool. With a simple command like curl -I, you can send a HEAD request to a URL and retrieve only the headers—think status codes, content type, and file size—without the body. This approach is fast, bandwidth-efficient, and perfect for tasks like confirming resource availability or scouting API endpoints.
Want an even more streamlined API experience? ApyHub provides a powerful suite of API tools that simplify testing and automation.

What is cURL HEAD Requests?

A cURL HEAD request is an HTTP request that retrieves only the headers of a response without the actual body content. It is useful for checking metadata, such as content type, length, or server information, without downloading the entire resource.

Why Use HEAD Requests for API Testing?

HEAD requests are an essential part of API testing and debugging. They allow you to:
  • Check for resource availability
  • Validate response headers
  • Optimize network efficiency

How to Use a cURL HEAD Request

To use a cURL HEAD request, you can follow these simple steps:

1. Basic cURL HEAD Request

This will only fetch the response headers of a URL, not the body. The -I or --head option specifies the HEAD method.
Syntax:
1
curl -I <URL>
Example:
1
curl -I https://www.example.com
Example Output:
1
HTTP/2 200
2
date: Fri, 14 Mar 2025 12:34:56 GMT
3
content-type: text/html; charset=UTF-8
4
content-length: 12345
5
server: Apache
The output includes status code, date, content type, content length, etc.

2. Specifying Headers with the Request

You can include custom headers in the HEAD request by using the -H flag. For example, to check if an API endpoint supports a specific Accept header:
1
curl -I -H "Accept: application/json" https://api.example.com/endpoint

3. Using HEAD Request to Check Response Time

Measure the response time by redirecting the output to /dev/null and using the -w flag to print the time:
1
curl -o /dev/null -s -w "%{time_total}\n" -I https://www.example.com
This will show the total time it took for the server to respond.

4. Additional Options

  • Follow redirects: If the server responds with a redirect (HTTP 3xx), use -L:
    1
    curl -I -L https://www.example.com
  • Show verbose output: Use -v for detailed request/response info:
    1
    curl -I -v https://www.example.com

5. Using HEAD Request for API Testing

Check headers before making a full GET request:
1
curl -I https://api.example.com/data
This returns headers like content-type, status, or cache-control.

Real-World Applications and Scenarios

cURL HEAD requests solve real problems. Here’s how developers use them:

1. Bulk URL Validation

Check multiple links programmatically:
1
for url in $(cat urls.txt); do
2
    status=$(curl -I -s -o /dev/null -w "%{http_code}" "$url")
3
    echo "$url: $status"
4
done
Status Codes:
200 = Good, 404 = Gone, 301 = Redirected.

2. Pre-Download Size Checks

Check file size before downloading:
1
curl -I https://example.com/downloads/app.zip
Look for Content-Length in the response headers.

3. Freshness Tracking

Check when a resource was last modified:
1
curl -I https://example.com/news/article
Look for Last-Modified in headers.

4. API Scouting

Test API availability:
1
curl -I https://api.weather.com/v1/forecast
A 200 OK means it’s live; 403 Forbidden indicates access issues.

Advanced Techniques and Integrations

1. Automate Site Monitoring

Create a script to monitor URLs:
1
#!/bin/bash
2
urls=("https://example.com" "https://api.example.com")
3
for url in "${urls[@]}"; do
4
    status=$(curl -I -s -o /dev/null -w "%{http_code}" "$url")
5
    if [ "$status" -ne 200 ]; then
6
        echo "Alert: $url is down (Status: $status)"
7
    fi
8
done
Run via cron for continuous monitoring.

2. Hook Into Monitoring Tools

Integrate with Prometheus for lightweight checks:
1
- job_name: 'site_health'
2
  http:
3
    method: HEAD
4
  static_configs:
5
    - targets: ['https://example.com']

3. Inspect Redirects

Check redirect headers without following them:
1
curl -I https://example.com
Look for 301 status and Location headers.

4. Parse with Tools

Extract custom headers using jq:
1
curl -I https://api.example.com/data | jq -R 'split("\r\n") | .[] | select(startswith("X-"))'
This filters headers like X-Rate-Limit.

Best Practices for Using cURL HEAD Requests

  • Validate URLs before executing commands.
  • Use -v for debugging, but disable it in production scripts.
  • Avoid -k (insecure SSL) in sensitive environments.
  • Monitor API rate limits for bulk requests.
  • Automate with Bash/Python scripts.

Conclusion

cURL HEAD requests are a lean, efficient way to probe web resources and APIs. They deliver critical insights—like status codes and metadata—without downloading full content. From bulk URL checks to API monitoring, they’re a must-have tool for developers.
elect

Frequently Asked Questions (FAQ)

Can I use cURL HEAD requests with authentication?
Yes! Use -u username:password for basic auth or -H "Authorization: Bearer <token>" for tokens.
Can I limit the request timeout?
Yes, use --max-time <seconds>:
1
curl -I --max-time 5 https://example.com
How to use cURL behind a proxy?
Specify the proxy with -x:
1
curl -I -x http://proxyserver:port https://example.com
How to check API rate limits?
Extract headers like X-Rate-Limit-Remaining:
1
curl -I https://api.example.com | grep "X-Rate-Limit"
How to save headers to a file?
Use -o:
1
curl -I https://example.com -o headers.txt
Where to find ApyHub’s API tools?
elect