API documentation

Guide on how to utilise the API effectively.

Introduction

Uses

With the HttpStatus web interface you can easily check the HTTP status code, status message, response headers, and redirect chain of URLs.

You can check a limited number of URLs at once using the web interface, and the results of each check can be exported into spreadsheet documents for storage or processing.

For situations where you need to frequently check URLs, it may be beneficial to automate the process. Additionally, having the flexibility to choose the form and tooling for processing results (the API is compatible with various applications and scripting languages) can be advantageous. In such cases, utilizing an API is often a suitable option.

How it works

Similar to the HttpStatus web interface, the API has an endpoint for sending a GET request to the specified URL. The API endpoint can be accessed via HTTPS using a POST request, where all input is managed through a JSON body object, and it returns a JSON response.

While the tool's web interface enables checking a restricted batch of URLs simultaneously, the API permits checking only one URL per request.

NOTE  This API will only send requests using version 1.1 of the HTTP protocol.

Packed with features

  • Experience the full package: returns status codes, redirect chains, response headers and response bodies.
  • Redirect hop limits: provides flexibility in handling redirects by defining the specific number of redirect responses the API should follow.
  • IPv4 and IPv6 protocols: by connecting via IPv4 or IPv6 protocols, check whether URLs successfully support both protocols.
  • Set user-agent strings: effortlessly explore how URLs respond across various user agents by using predefined or custom user-agent strings.
  • Certificate validation: validating URLs for the authenticity of TLS certificates is straightforward due to the built-in validation function.
  • Custom request headers: send any combination of request headers to audit the response of URLs to specific request headers.
  • HTTP Basic authentication: access protected resources by sending the username and password in the "Authorization" header of each request.
  • URL parser: the built-in URL parser splits each URL or redirection location into readable parts for easy analysis.
  • Hostname parser: the built-in hostname parser extracts domains, subdomains and public suffixes (ICANN and private TLDs) from complex URIs.
  • Redirect latency: measure latency of each redirect in the redirect chain and verify the total delay to get from the initial URL to the final destination URL.
  • IP address: easily explore the IPv4 or IPv6 address of every redirect location in the chain.
  • Redirect types: identify whether a URL redirects to another URL on the same domain or origin (same-origin), or to a URL on a different origin (cross-origin).
  • Metadata: get metadata such as title, meta description, canonical link tag, etc. for the destination URL.
  • Secure connections only: only supports HTTPS connections, ensuring that your information is transmitted safely and securely.
  • CORS support: allows cross-domain requests in the browser.

API Reference

Use this endpoint to check the status of a single URL.

POST  https://api.httpstatus.io/v1/status

Parameters

Body

ParameterTypeDefaultDescriptionRequired
requestUrlstring

The URL to fetch the status for. Use a URL without a specified scheme, which defaults to HTTP, or include an HTTP or HTTPS scheme.

Yes
followRedirectbooleantrue

Defines if redirect responses should be followed automatically. Defaults to true.

No
maxRedirectsinteger10

Sets a specific number of redirect responses for the API to follow. If this value is exceeded, the request will be aborted and an error message will be returned. Defaults to 10 redirects.

No
responseBodybooleanfalse

When set to true, the response body of the final URL is returned. Defaults to false.

No
responseHeadersbooleanfalse

When set to true, the response headers of all URLs within the chain are returned. Defaults to false.

No
requestHeadersbooleanfalse

When set to true, the request headers of all URLs within the chain are returned. Defaults to false.

No
rawRequestbooleanfalse

When set to true, the raw request (containing the http method, resource, http version and request headers) of all URLs within the chain are returned. Defaults to false.

No
userAgentstringdefault

Set the 'user-agent' header to test the response under different strings. The default user-agent contains the following string: "HttpStatus (+https://httpstatus.io/ua)"

Possible values: browser (client/browser from where request is sent), googlebot-desktop, googlebot-smartphone, bingbot-desktop, bingbot-mobile, yandexbot, applebot-desktop, applebot-mobile, duckduckbot, iphone, ipad, android, samsung-internet, edge, ie11, chrome, firefox, safari, twitterbot, linkedinbot, facebook-crawler, slackbot-link-expanding, slackbot, ccbot, gptbot, google-other, chatgpt-user, none, httpstatus

Strings from predefined and custom user-agents (using a user-agent request header) contain a reference to HttpStatus, indicating that the request originates from HttpStatus but simulates a different user-agent.

No
parsedUrlbooleanfalse

When set to true, the returned URLs inside the redirect chain array contain the following properties:

protocol, slashes, auth, username, password, host, hostname, port, pathname, query, hash, href, origin		No
parsedHostnamebooleanfalse

When set to true, the returned URLs inside the redirect chain array contain the following properties:

domain, domainWithoutSuffix, hostname, isIcann, isIp, isPrivate, publicSuffix, subdomain		No
timingsbooleanfalse

When set to true, the returned URLs inside the redirect chain array contain a timings object with the following properties (the time is a number representing the milliseconds elapsed since the UNIX epoch):

start, socket, lookup, connect, secureConnect, upload, response, end, error, abort

The timings object also contains a phases object with the following properties (if something has not been measured yet, it will be undefined):

wait, dns, tcp, tls, request, firstByte, download, total		No
setRequestHeadersobject

Custom request headers that you can send with the request. You can also use a custom header to send your own user-agent string (this will overwrite the existing user-agent).

No
usernamestring

A username for HTTP Basic authentication. Send the server authentication credentials (authorization header) for basic access authentication.

No
passwordstring

A password for HTTP Basic authentication. Send the server authentication credentials (authorization header) for basic access authentication.

No
validateTlsCertificatebooleantrue

Validate the server's TLS certificate, and treat it as an error if there are any problems with it. (This includes self-signed certificates).

No
httpsbooleanfalse

Set which scheme (http:// or https://) is used for request URLs without a scheme (eg. www.google.com).

No
dnsLookupIpVersioninteger4

Set which IP version (IPv4 or IPv6) is used for a request. Provides the ability to verify that sites can be accessed through both IPv4 and IPv6 addresses via a dual-stack configuration.

Possible values: 4 or 6

No
metabooleanfalse

When set to true, the returned destination URL includes a metaData object that contains the following metadata properties about the destination URL:

title, meta description, meta robots, meta keywords, canonical link tag, hreflang tags, language, provider, image, icon, type, author, published, modified

Note that properties and values are only returned if they are present in the HTML source.

No

Headers

ParameterTypeDescriptionRequired
Content-Typestring

Set the header value to 'application/json; charset=utf-8' to receive the response as a application/json content type.

Yes
X-Billing-Tokenstring

Send your access key (available after subscription) in the "X-Billing-Token" header with each API call.

Yes

Request  Examples

curl -X "POST" "https://api.httpstatus.io/v1/status" \
     -H 'x-billing-token: 4af9c46e320f5acf2ba452d5ac4f89d33043267a1f2312d59eba68505e6c3ab71ad55d320b1c17ba7f696ce14f056fcb32df30cf0075923cc0d8d873142f5c2a' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "requestUrl": "wikipedia.com"
}'

Responses  Examples

{
  "metaData": {
    "version": "v1",
    "responseTime": 8,
    "dateTime": "2023-12-16T19:22:10.232Z"
  },
  "requestSettings": {
    "custom": {
      "requestUrl": "http://wikipedia.com",
      "https": false,
      "followRedirect": true,
      "maxRedirects": 10,
      "validateTlsCertificate": true,
      "dnsLookupIpVersion": 4,
      "responseBody": false,
      "responseHeaders": false,
      "requestHeaders": false,
      "timings": false,
      "parsedUrl": false,
      "parsedHostname": false,
      "rawRequest": false,
      "meta": false,
      "userAgent": "default"
    },
    "fixed": {
      "httpVersion": "1.1",
      "method": "GET",
      "timeout": 10000,
      "setHost": "true",
      "http2": false,
      "encoding": "utf-8",
      "decompress": true
    }
  },
  "response": {
    "numberOfRedirects": 2,
    "chain": [
      {
        "url": "http://wikipedia.com/",
        "statusCode": 301,
        "statusMessage": "Moved Permanently",
        "redirectFrom": "http://wikipedia.com/",
        "redirectTo": "https://wikipedia.com/",
        "ip": "185.15.59.226",
        "latency": 151,
        "redirectType": "same-origin"
      },
      {
        "url": "https://wikipedia.com/",
        "statusCode": 301,
        "statusMessage": "Moved Permanently",
        "redirectFrom": "https://wikipedia.com/",
        "redirectTo": "https://www.wikipedia.org/",
        "ip": "185.15.59.226",
        "latency": 61,
        "redirectType": "cross-origin"
      },
      {
        "url": "https://www.wikipedia.org/",
        "statusCode": 200,
        "statusMessage": "OK",
        "ip": "185.15.59.224"
      }
    ]
  }
}

Rate limits

A rate limit is enabled for each specific plan. The rate limit specifies the number of requests (calls) per second (rps) that will be accepted by the API endpoint.

If too many requests are sent to the endpoint within a second, a 429 response (Too Many Requests) will be returned. Use a sleep function to wait between API calls to avoid exceeding the limit.

Quotas

Each specific plan has either a soft or hard quota limit. If a hard quota limit is exceeded, access to the endpoint is restricted for the remainder of the month. However, in the case of a plan with a soft limit, exceeding the limit will automatically activate a pay-as-you-go (PAYG) plan. This means that any additional usage over the limit will be charged at the overage rate.

For a hard quota limit the status can be viewed via the following response header:

HeaderExampleDescription
X-Quota label=callspermonth; limit-type=hard; quota=20000; remaining=18969; usage=1031; call-usage=1; reset=268395 Information about the number of requests that the client will be able to make in the time window.

This information can also be tracked within your Nadles API dashboard.


If you have any questions, I'll be happy to help you get on board.

Ask a question
This website uses cookies to ensure you get the best experience. By using this website, you acknowledge that you understand and agree to our Privacy Policy and Terms and Conditions.