Axios HEAD Request Syntax and Examples

An HTTP HEAD request retrieves the response headers from a server without downloading the actual response body, making it an efficient way to check document metadata, cache validity, or resource existence. In Axios, you can issue a HEAD request either by using the dedicated shorthand method axios.head() or by passing { method: 'head' } into the general axios() request configuration. This guide covers the exact syntax, code examples, and how to inspect the returned headers.

1. Using the axios.head() Shorthand

The primary syntax for executing a HEAD request is the axios.head() convenience method.

Syntax

axios.head(url[, config])

• url: The target endpoint URL (string).
• config (optional): An object containing custom configurations such as headers, query parameters, or timeout settings.

Example

const axios = require('axios');

async function checkResource() {
  try {
    const response = await axios.head('https://api.example.com/data', {
      headers: {
        'Authorization': 'Bearer token_here'
      },
      params: {
        version: '1.0'
      }
    });

    console.log(`Status: ${response.status}`);
    console.log('Headers:', response.headers);
    console.log('Content-Type:', response.headers['content-type']);
    console.log('Content-Length:', response.headers['content-length']);
  } catch (error) {
    if (error.response) {
      console.error(`Resource check failed with status: ${error.response.status}`);
    } else {
      console.error('Request error:', error.message);
    }
  }
}

checkResource();

2. Using the Generic axios(config) Syntax

You can also send a HEAD request by specifying 'head' as the method property inside a standard Axios request object.

Syntax

axios({
  method: 'head',
  url: 'https://api.example.com/data',
  // optional configuration
  headers: {},
  params: {}
})

Example

const axios = require('axios');

axios({
  method: 'head',
  url: 'https://api.example.com/data'
})
  .then(response => {
    console.log('Status Code:', response.status);
    console.log('Last-Modified:', response.headers['last-modified']);
  })
  .catch(error => {
    console.error('Error fetching headers:', error);
  });

3. Working with the Response Object

Because a HEAD request does not return a message body, the returned Axios response properties behave as follows:

• response.headers: An object containing all HTTP headers sent back by the server.
• response.status: The HTTP status code (e.g., 200, 304, 404).
• response.data: An empty string "", since no response payload is transferred.