--- title: "How to Use cURL HEAD Requests: A Developer’s Guide" url: https://apyhub.com/blog/curl-head-request author: Sohail Pathan published: 2025-03-14T00:00:00Z tags: [engineering] --- # 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](https://apyhub.com) 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:** ```sh curl -I ``` **Example:** ```sh curl -I https://www.example.com ``` **Example Output:** ```yaml HTTP/2 200 date: Fri, 14 Mar 2025 12:34:56 GMT content-type: text/html; charset=UTF-8 content-length: 12345 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: ```sh 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: ```sh 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`: ```sh curl -I -L https://www.example.com ``` - **Show verbose output**: Use `-v` for detailed request/response info: ```sh curl -I -v https://www.example.com ``` ### 5. Using HEAD Request for API Testing Check headers before making a full GET request: ```sh 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: ```bash for url in $(cat urls.txt); do status=$(curl -I -s -o /dev/null -w "%{http_code}" "$url") echo "$url: $status" done ``` **Status Codes:** `200` = Good, `404` = Gone, `301` = Redirected. ### 2. Pre-Download Size Checks Check file size before downloading: ```sh 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: ```sh curl -I https://example.com/news/article ``` Look for `Last-Modified` in headers. ### 4. API Scouting Test API availability: ```sh 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: ```bash #!/bin/bash urls=("https://example.com" "https://api.example.com") for url in "${urls[@]}"; do status=$(curl -I -s -o /dev/null -w "%{http_code}" "$url") if [ "$status" -ne 200 ]; then echo "Alert: $url is down (Status: $status)" fi done ``` Run via `cron` for continuous monitoring. ### 2. Hook Into Monitoring Tools Integrate with Prometheus for lightweight checks: ```yaml - job_name: 'site_health' http: method: HEAD static_configs: - targets: ['https://example.com'] ``` ### 3. Inspect Redirects Check redirect headers without following them: ```sh curl -I https://example.com ``` Look for `301` status and `Location` headers. ### 4. Parse with Tools Extract custom headers using `jq`: ```sh 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](https://assets.apyhub.com/blog/head-request-blog/discover-cta3-1.png)](https://apyhub.com) ## Frequently Asked Questions (FAQ) **Can I use cURL HEAD requests with authentication?** Yes! Use `-u username:password` for basic auth or `-H "Authorization: Bearer "` for tokens. **Can I limit the request timeout?** Yes, use `--max-time `: ```sh curl -I --max-time 5 https://example.com ``` **How to use cURL behind a proxy?** Specify the proxy with `-x`: ```sh curl -I -x http://proxyserver:port https://example.com ``` **How to check API rate limits?** Extract headers like `X-Rate-Limit-Remaining`: ```sh curl -I https://api.example.com | grep "X-Rate-Limit" ``` **How to save headers to a file?** Use `-o`: ```sh curl -I https://example.com -o headers.txt ``` **Where to find ApyHub’s API tools?** [![elect](https://assets.apyhub.com/blog/head-request-blog/discover-cta2-new2.png)](https://apyhub.com)