Skip to content

Pagination

Learn how to handle large result sets using pagination parameters.

Query Limits

Too Many Results

The API returns domains only if there are fewer than 10,000 matching domains. Use filter parameters to narrow your results.

Searches with >10,000 results return a HTTP 200 response and code: 413 in the response body. For example, this search for a common nameserver_domain:

https://api.domaintools.com/v1/iris-investigate/?nameserver_domain=markmonitor.zone

Returns:

{
  "response": {
    "error": {
      "code": 413,
      "message": "More than 10000 matched - you may need to refine your query."
    },
    "limit_exceeded": true,
    "has_more_results": true,
    "message": "Maximum 10000 returned - you may need to refine your query.",
    "missing_domains": []
  }
}

Paginated Results

Queries with more than 500 and fewer than 10,000 results return HTTP 200 with the partial results, with a default response of 500. For example:

https://api.domaintools.com/v1/iris-investigate/?redirect_domain=domaintools.com

This response snippet shows how it includes both "limit_exceeded": false and "has_more_results": true, which means that the request is within your response limit, and more results are available. It also returns the position field to use for pagination.

{
  "response": {
    "limit_exceeded": false,
    "has_more_results": true,
    "message": "There is more data for you to enjoy.",
    "results_count": 500,
    "total_count": 1381,
    "position": "f825bb76cd46471482e016f944b1131d",
    "results": [
      {
        "domain": "vilamoda.com",
        ...

Using the position Parameter

Note that position is both the field name, and the query parameter name. Using the position string from the response object above, we page to the next 500 results:

https://api.domaintools.com/v1/iris-investigate/?redirect_domain=domaintools.com&position=f825bb76cd46471482e016f944b1131d

The final page of results is indicated by has_more_results flipping to false and a results_count: <500.

Using the next Parameter

Include next=true for >500 results (with the default 500 response page size) and the response will include a next field. The next field appears below position and contains the URL of the API call for the next page of results (including your query parameters).

A request for https://api.domaintools.com/v1/iris-investigate/?redirect_domain=domaintools.com&next=true returns a response with the next field:

{
  "response": {
    "limit_exceeded": false,
    "has_more_results": true,
    "message": "There is more data for you to enjoy.",
    "results_count": 500,
    "total_count": 1381,
    "position": "c5eedcc23a144b88917adb8a6194d7a4",
    "next": "https://api.domaintools.test2/v1/iris-investigate/?redirect_domain=domaintools.com&next=true&position=c5eedcc23a144b88917adb8a6194d7a4",
    "results": [
      {
    ...

The API will stop emitting the next field in response to the next=true parameter once it reaches the last page of results.

Using page_size to Limit Page Size

The page size default is 500 and the page_size parameter can make the page size smaller. The following example HTTP GET request URL specifies a page_size of 100:

https://api.domaintools.com/v1/iris-investigate/?redirect_domain=domaintools.com&page_size=100

Sorting Results

Using sort_by

Sorting defaults to descending order of first_seen_since when no sorting method is specified, as in results for this query:

https://api.domaintools.com/v1/iris-investigate/?nameserver_domain=markmonitor.zone

Use the sort_by parameter to sort by:

  • first_seen_since (default sort method; defaults to descending)
  • create_date (default: descending)
  • domain (default: ascending)
  • risk_score (default: ascending)

For example, use sort_by to sort by risk_score:

https://api.domaintools.com/v1/iris-investigate/?redirect_domain=domaintools.com&sort_by=risk_score

Using sort_direction

Beginning with a query that sorts a list of domain results by risk_score with default ascending order:

https://api.domaintools.com/v1/iris-investigate/?redirect_domain=domaintools.com&sort_by=risk_score

Now, with results in descending order with &sort_direction=dsc:

https://api.domaintools.com/v1/iris-investigate/?redirect_domain=domaintools.com&sort_by=risk_score&sort_direction=dsc

This also works with create_date and first_seen_since.

See Also