Requests

All of the API endpoints listed below conform to the same syntax of being appended to the end of an authenticated query, which will always begin with https://investigate.api.umbrella.com/.

Once you have your access token, follow the syntax in this example. Using the cURL command line, substitute your token for the %variable%:

curl -i -H "Authorization: Bearer %YourToken%" "https://investigate.api.umbrella.com/dnsdb/name/a/example.com.json"

This request should return HTTP/1.1 200 OK and results from Investigate. If it does not, look to the HTTP codes to determine if the command or token are valid. For future queries, remove the -i to return only results from Investigate. Nearly all requests to Investigate are GET requests; the only exception is a POST request Domain Status for multiple domains.

Requests can also be done directly in a browser that's already authenticated with Investigate by entering the URL of the query in the address bar.

Information about Rate Limiting

The API is rate limited in order to ensure the best possible performance for all customers. The limits are different based on the tier of API access that was purchased and which endpoint is being requested. The rate limit is based on the organization that owns the API key used, and the rate limit is shared across all of a given organization's API keys.

For the Domain Status and Categorization endpoint (/domains/), the rate limit is:

Tier 1 - 3 requests per second
Tier 2 - 300 requests per second
Tier 3 - 300 requests per second

Only Tier 2 and 3 are able to make bulk submissions to the categorization endpoint.

For these endpoints: /timeline, /volume, /search, /recommendations, /links, /security, /bgp_routes, /topmillion , the rate limit is:
Tier 1 - 3 requests per second
Tier 2 - 12 requests per second
Tier 3 - 12 requests per second

For these endpoints: /whois, /dnsdb, /samples, the rate limit is as follows, note the specific difference for Tier 3:
Tier 1 - 3 requests per second
Tier 2 - 12 requests per second
Tier 3 - 48 requests per second

When the rate limit for an endpoint is exceeded, all additional requests above the limit will receive an HTTP 503 response (Service Unavailable) and are discarded. Requests can be resent in a subsequent batch at the next interval (one second later).


Coding Examples < Requests > Error Handling

Requests