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

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 APIs and 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:

1curl -I <URL>

Example:

1curl -I https://www.example.com

Example Output:

1HTTP/2 2002date: Fri, 14 Mar 2025 12:34:56 GMT3content-type: text/html; charset=UTF-84content-length: 123455server: 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:

1curl -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:

1curl -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:

    1curl -I -L https://www.example.com
  

• Show verbose output: Use -v for detailed request/response info:

    1curl -I -v https://www.example.com
  

5. Using HEAD Request for API Testing

Check headers before making a full GET request:

1curl -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:

1for url in $(cat urls.txt); do2    status=$(curl -I -s -o /dev/null -w "%{http_code}" "$url")3    echo "$url: $status"4done

Status Codes:
200 = Good, 404 = Gone, 301 = Redirected.

2. Pre-Download Size Checks

Check file size before downloading:

1curl -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:

1curl -I https://example.com/news/article

Look for Last-Modified in headers.

4. API Scouting

Test API availability:

1curl -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/bash2urls=("https://example.com" "https://api.example.com")3for url in "${urls[@]}"; do4    status=$(curl -I -s -o /dev/null -w "%{http_code}" "$url")5    if [ "$status" -ne 200 ]; then6        echo "Alert: $url is down (Status: $status)"7    fi8done

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: HEAD4  static_configs:5    - targets: ['https://example.com']

3. Inspect Redirects

Check redirect headers without following them:

1curl -I https://example.com

Look for 301 status and Location headers.

4. Parse with Tools

Extract custom headers using jq:

1curl -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.

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>:

1curl -I --max-time 5 https://example.com

How to use cURL behind a proxy?
Specify the proxy with -x:

1curl -I -x http://proxyserver:port https://example.com

How to check API rate limits?
Extract headers like X-Rate-Limit-Remaining:

1curl -I https://api.example.com | grep "X-Rate-Limit"

How to save headers to a file?
Use -o:

1curl -I https://example.com -o headers.txt

Where to find ApyHub’s API APIs?

here: https://apyhub.com/catalog