Iris Investigate API Guide¶

Overview¶

The Iris Investigate API is ideally suited for investigate and orchestrate use cases at human scale.

Consult the OpenAPI reference for the Iris API suite for additional detail.

Key characteristics of the Iris Investigate API include:

Dozens of domain name attributes on every result, including:
Domain risk scores from proximity and threat profile algorithms
RDAP, WHOIS, IP, active DNS, website & SSL data
Counts of connected domains on most attributes
Unified API endpoint for both domain profiles & pivot searches
Support for batch processing and pagination
Search by identity, IP, name server, mail server, SSL certificate, & more
Offered with interactive Iris web app

Getting Started¶

API Endpoint¶

https://api.domaintools.com/v1/iris-investigate/

API Authentication¶

The Iris APIs share the same authentication mechanisms as DomainTools Feeds.

Link your credentials to your organization's DomainTools enterprise account, which must be authorized for Iris Investigate.

Use Header Authentication by passing your API key in the X-Api-Key header field (example below).

Query Limits and Testing¶

Note

Test and configure with no-charge test queries.

Use no-charge test queries for configuration: ?domain=domaintools.com and ?ip=199.30.228.112.

Retrieve Domain Records with a Test Query¶

Submit a HTTP GET request:

Query URLcURL Example

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

curl -X GET \
  'https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com' \
  -H 'X-Api-Key: YOUR_API_KEY'

The API returns default records for domaintools.com as objects in the results array.

{
  "response": {
    "limit_exceeded": false,
    "has_more_results": false,
    "message": "Enjoy your data.",
    "results_count": 1,
    "total_count": 1,
    "results": [
      {
        "domain": "domaintools.com",
        "whois_url": "https://whois.domaintools.com/domaintools.com",
        "adsense": {
          "value": "",
          "count": 0
        },
        ...
      }
    ]
  }
}

Search for a Set of Domain Names¶

Search for a single domain name:

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

Pass a comma-separated list of up to 100 domain names in a HTTP GET request:

Query URLcURL Example

https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com,domaintools.net,example.com

curl -X GET 'https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com,domaintools.net,example.com' \
-H 'X-Api-Key: YOUR_API_KEY'

Consider using a POST request for multiple domains:

curl -X POST 'https://api.domaintools.com/v1/iris-investigate/' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'X-Api-Key: YOUR_API_KEY' \
-d 'domain=domaintools.com,domaintools.net,example.com'

Use Base Search and Search Filter Parameters¶

Iris Investigate supports a set of base search parameters, and filter parameters. Base search parameters can be used on their own or in combination with each other, while filter parameters refine the base search.

Instead of a domain name, you can provide one or more search fields to the API, such as IP address, SSL hash, email, or more, and Iris Investigate will return any domain name with a record that matches those parameters. This enables "reverse" searching on one or more fields with a single API endpoint.

Search for all domains linked to the IP address 199.30.228.112:

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

Queries across multiple parameters are interpreted as a logical AND query, meaning multiple parameters will narrow a search to a smaller result set. The Iris Investigate API does not currently support logical OR queries.

Domain records returned in the result set are identical to records returned from a query for one or more domain names. For example, consider using the guided pivot counts to surface new ways to expand the result set. Or, you could sort on the risk score (highest to lowest) to show the results to the end user with riskiest domains listed first.

Base Search Parameters¶

Description: Google AdSense tracking code

baidu_analytics¶

Description: Baidu analytics code

contact_name¶

Description: Contact name from domain registration data

Supports WHOIS/RDAP Fields Search: Yes

contact_phone¶

Description: Contact street address from domain registration data

Supports WHOIS/RDAP Fields Search: Yes

contact_street¶

Description: Contact street address from domain registration data

Supports WHOIS/RDAP Fields Search: Yes

domain¶

Description: Apex domain

email¶

Description: Email address from the most recently available WHOIS record, DNS SOA record or SSL certificate

Supports WHOIS/RDAP Fields Search: Yes - for registration emails

Compare To: Reverse WHOIS

email_dns_soa¶

Description: DNS SOA email

email_domain¶

Description: Apex domain portion of a WHOIS or DNS SOA email address

Supports WHOIS/RDAP Fields Search: Yes - for registration emails

Compare To: Reverse WHOIS

facebook¶

Description: Facebook/Meta tracking code

google_analytics¶

Description: Google Analytics tracking code

google_analytics_4¶

Description: Google Analytics 4 tracking code

google_tag_manager¶

Description: Google Tag Manager tracking code

historical_email¶

Description: Email addresses from historical WHOIS records

historical_free_text¶

Description: Free text search of a domain's historical WHOIS records - compare to whois

historical_registrant¶

Description: Registrant names from historical WHOIS records

hotjar¶

Description: Hotjar tracking code

iana_id¶

Description: Registrar IANA code from most recent RDAP record for a domain

ip¶

Description: IPv4 address the registered domain was last known to point to during an active DNS check

Compare To: Reverse IP

mailserver_domain¶

Description: Only the registered domain portion of the mail server (domaintools.net)

mailserver_host¶

Description: Fully-qualified host name of the mail server (mx.domaintools.net)

Compare To: Reverse MX

mailserver_ip¶

Description: IP address of the mail server

matomo¶

Description: Matomo tracking code

nameserver_domain¶

Description: Registered domain portion of the name server (domaintools.net)

Compare To: Reverse Nameserver

nameserver_host¶

Description: Fully-qualified host name of the name server (ns1.domaintools.net)

nameserver_ip¶

Description: IP address of the name server

redirect_domain¶

Description: Find domains observed to redirect to another domain name

registrant¶

Description: Substring search on the WHOIS registrant field

Supports WHOIS/RDAP Fields Search: Yes

Compare To: Reverse WHOIS

registrant_org¶

Description: Substring search on the WHOIS registrant org field

Supports WHOIS/RDAP Fields Search: Yes

Compare To: Reverse WHOIS

registrar¶

Description: Exact match to the WHOIS registrar field

Supports WHOIS/RDAP Fields Search: Yes

Compare To: Reverse WHOIS

search_hash¶

Description: Encoded search from the Iris Investigate UI

server_type¶

Description: Most recent server type retrieved from screenshot gathering

ssl_alt_names¶

Description: Query elements/labels from a list of domains/subdomains in certificate Subject Alt Name lists

ssl_common_name¶

Description: Certificate Common Name

ssl_duration¶

Description: Certificate validity duration, in number of days

ssl_email¶

Description: Email address from the SSL certificate

ssl_hash¶

Description: SSL certificate SHA-1 hash

ssl_issuer_common_name¶

Description: Certificate issuer Common Name

ssl_org¶

Description: Exact match to the organization name on the SSL certificate

ssl_subject¶

Description: Subject field from the SSL certificate

statcounter_project¶

Description: Statcounter Project tracker code

statcounter_security¶

Description: Statcounter Security tracker code

tagged_with_all¶

Description: Domain tagged with all tags

tagged_with_any¶

Description: Domains tagged with a specific Iris Tag

website_title¶

Description: HTML title from most recent screenshot

whois¶

Description: Free text search of a domain's most recent WHOIS record - compare to historical_free_text

yandex_metrica¶

Description: Yandex tracker code

These parameters can be added to any search in the Iris Investigate API, although they cannot be used on their own.

For example, search for domaintools.com and domaintools.net with a filter for a .com TLD will surface domaintools.com as a result:

https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com,domaintools.net&tld=com

active¶

Description: true returns domains that have an entry in the global DNS, OR are listed as registered by the registry. false returns domains that are not in global DNS, AND are not listed as registered by the registry. Exclude filter to return all domains.

create_date¶

Description: Only include domains created on a specific date, in YYYY-MM-DD format

Supports WHOIS/RDAP Fields Search: Yes

expiration_date¶

Description: Only include domains expiring on a specific date, in YYYY-MM-DD format

Supports WHOIS/RDAP Fields Search: Yes

first_seen_since¶

Description: Matches domains with a first seen on or after an ISO8601-compliant date/time (including a timezone)

first_seen_within¶

Description: Matches domains with a first seen within a specific number of seconds from when the request is made

ip_country_code¶

Description: Country code for IP A-record

not_tagged_with_all¶

Description: A tag or comma-separated list of tags. Filters for domain that are not tagged with any of the provided tags.

not_tagged_with_any¶

Description: A tag or a comma-separated list of tags. Filters for domains that are not tagged with any of the provided tags.

rank¶

Description: Popularity rank (replaces Alexa ranking)

risk_score¶

Description: Domain Risk Score

server_type¶

Description: The web server type

ssl_not_after¶

Description: Validity end date for a certificate (YYYY-MM-DD)

ssl_not_before¶

Description: Validity begin date for a certificate (YYYY-MM-DD)

tagged_with_all¶

Description: A tag or comma-separated list of tags. Filters for domain that are tagged with all of the provided tags.

tagged_with_any¶

Description: A tag or a comma-separated list of tags. Filters for domains that are tagged with any of the provided tags.

tld¶

Description: Limit results to only include domains in a specific top-level domain (i.e., tld=com, tld=ru)

website_title¶

Description: The value of the website's title tag

Search and Filter within Parsed WHOIS and Parsed Domain RDAP Fields¶

Filter by a specific component within a parsed_whois or parsed_domain_rdap field. For example, filter by Create Date in Parsed WHOIS:

https://api.domaintools.com/v1/iris-investigate/?domain=github.com&parsed_whois:create_date=2007-10-09

Query Quota Consumption¶

Understanding what counts as quota consumption helps you optimize your API usage. The system measures quotas at the group level and resets them each month.

Duplicate Query Policy for API¶

Identical API queries within 1 hour do not count against quota. A query is considered identical if it has the same parameters (filters, sorting, pagination) as a previous query made within the last hour.

Activities That Consume Quota¶

The following API activities consume your quota:

Executing a query
Loading additional pages of results

Activities That Do Not Consume Quota¶

The following API activities do not consume your quota:

Identical queries made within 1 hour of a previous query that counted toward quota

For complete details on quota consumption policies, including UI-specific policies, search hash reloading, and revisiting search nodes, consult the Iris API Rate Limits documentation.

Query Limits & Pagination¶

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",
        ...

Use the `position` Parameter to Page Through Results¶

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.

Use the `next` Parameter to Automatically Generate the URL for the Next Page of Results¶

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=truereturns 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.

Use `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

Use `sort_by` to Sort Results by `first_seen_since`, `create_date`, `domain`, or `risk_score`¶

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

Use `sort_direction` to Set the 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.

Compare WHOIS and Domain RDAP Records (new in 2025)¶

By default, queries return standard registration data as part of the response root fields. Registration data is from either Domain RDAP or WHOIS, depending on which record is more complete.

Add a standalone set of parsed fields from the Domain RDAP and/or the WHOIS record to the response with the parameters parsed_domain_rdap=true and &parsed_whois=true. For example, extend the above example query for domaintools.com by requesting Parsed Domain RDAP records in addition to the default response:

Submit a HTTP GET request:

Query URLcURL Example

https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com&parsed_domain_rdap=true

curl -X GET \
  'https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com&parsed_domain_rdap=true&' \
  -H 'X-Api-Key: YOUR_API_KEY'

The API response contains a results array. Each item in the array is a domain object, and within the object for domaintools.com, the parsed Domain RDAP record is returned as a nested object under the key parsed_domain_rdap."

{
  "response": {
    "message": "Enjoy your data.",
    "results_count": 1,
    "total_count": 1,
    "results": [
      {
        "//": "This is the single domain result object, contained within the 'results' array.",
        "domain": "domaintools.com",
        "popularity_rank": 2622,
        "active": true,
        "create_date": {
          "value": "1998-08-02",
          "count": 871
        },
        "//": "... Other top-level attributes for the domain are truncated ...",

        "parsed_whois": {
          "//": "This is the nested object for the parsed WHOIS data.",
          "registrar": {
            "value": "eNom, LLC",
            "count": 593475
          },
          "registrant_org": {
            "value": "DomainTools, LLC",
            "count": 3
          },
          "//": "... Other WHOIS fields truncated ..."
        },
        "parsed_domain_rdap": {
          "//": "This is the nested object for the parsed RDAP data.",
          "registrar": {
            "value": "ENOM, INC.",
            "count": 3448760
          },
          "registrant_contact": {
            "name": {
              "value": "REDACTED REGISTRANT",
              "count": 9948449
            }
          },
          "//": "... Other RDAP fields truncated ..."
        }
      }
    ]
  }
}

Use Domain Tags as a Base Search or Filter Parameter¶

Use Domain Tags as a Search Parameter¶

Search for domains that have already been tagged within the Iris Investigate UI. All Tags created within your instance of the Iris Investigate UI are accessible via the API.

Use tagged_with_any and tagged_with_all to perform base searches on tags:

Retrieve Domains matching one of the specified Tags¶

Sample Parameter: ?tagged_with_any=watch,monitor

Expected Result: All Domains which have been tagged as 'watch' OR 'monitor'

Retrieve Domains matching a list of Tags¶

Sample Parameter: ?tagged_with_all=block,dangerous,evil

Expected Result: All Domains which have been tagged with all 3 tags – 'block' and 'dangerous' and 'evil'

Use Domain Tags as a Search Filter¶

Limit base results by filtering for tagged domains:

Filter result sets by only displaying Domains matching one of the specified 'Tags'¶

Sample Parameter: ?nameserver_domain=markmonitor.zone&tagged_with_any=watch,monitor

Expected Result: Only list Domains which are tagged as 'watch' OR 'monitor'

Filter result sets by only displaying Domains matching a List of 'Tags'¶

Sample Parameter: ?nameserver_domain=markmonitor.zone&tagged_with_all=block,dangerous,evil

Expected Result: Only list Domains which are tagged with all 3 tags – 'watch' and 'dangerous' and 'evil'

Filter result sets by excluding domains matching one of the specified 'Tags'¶

Sample Parameter: ?nameserver_domain=markmonitor.zone¬_tagged_with_any=watch,monitor

Expected Result: Only list Domains which are not tagged with 'watch' or 'monitor'

Filter result sets by excluding domains matching a List of 'Tags'¶

Sample Parameter: ?nameserver_domain=markmonitor.zone¬_tagged_with_all=zerolisted,safe,trusted

Expected Result: Only list Domains which are not tagged as 'zerolisted' and 'safe' and 'trusted'

Guided Pivots with the Iris Investigate API¶

Guided pivots help identify attributes that are shared with a relatively small number of other domain names. The smaller the count, the more likely the domains are to be related.

The Iris Investigate API delivers these counts for nearly every attribute in a domain response, on every domain record, even when processing a batch of domain names.

These counts are included in the API response as a property of the attribute, adjacent to the attribute value. This also explains why the value of a field is one level deeper than you may expect. For example:

ip:
  [
    {
      address:
        { value: "199.30.228.112", count: 3 },
      asn:
        [
          { value: 17318, count: 101 }
    ],
      country_code: { value: "us", count: 239988363 },
      isp: { value: "Domaintools LLC", count: 108 }
    }
  ]

Here, we identify the IP address 199.30.228.112, ASN 17318 and ISP Domaintools LLC as potential pivot points, or at the very least, as meaningful analytics to help profile the domain name. For example, IP addresses with very few other domains pointed to them often represent dedicated hosting controlled by the same entity.

In the Iris Investigate UI, we use a default threshold of 500 connections to decide which attributes to draw the user's attention to. Consider starting with a similar threshold for your integration, but provide the user the option to choose a different threshold to match their use case.

Note that empty data elements will have a count of 0.

Monitoring newly active domains with the Iris Investigate API¶

The Iris Investigate API can be used as a powerful monitoring tool to detect newly active domains pointed to certain IPs, hosted on target name servers, redirecting to specific sites, and any other criteria that can be framed in an Iris Investigate API query.

This can be accomplished by adding either first_seen_since or first_seen_within to the API query (see details above for those parameters). The first seen is the date/time (in UTC) that DomainTools discovers a domain as newly active. A potential implementation may follow a pattern similar to this:

Craft a search query in Iris Investigate that defines the attributes you want to monitor.
Submit the query to Iris Investigate to obtain a baseline. Store the data in your own system.
Periodically re-submit the same query, but with the addition of the appropriate 'first seen' parameter based on when you last queried.

Then:

Compare to the stored baseline to find domains added or removed
Iterate through domains that were already present in the baseline snapshot but were since updated in some way. Compare to their base records and note the differences.
Store the additions, deletions, or updates as a new baseline, possibly preserving the previous values for historical tracking

This capability makes the Iris Investigate API a compelling replacement for DomainTools Enterprise API monitors that currently only return a single domain in their result: Name Server Monitor and IP Monitor. It also extends monitoring well beyond those endpoints to include monitoring on SSL attributes, tracking codes, registrar and more, with the additional option to narrow to specific TLDs with the tld filter.

Retrieve Screenshots¶

Retrieve the most recent screenshot for a given domain with Iris Investigate (and other Iris) APIs in a two-step process:

Retrieve the screenshot image URL
Retrieve and optionally resize the image file

Also consult the section on interpreting screenshot metadata, below.

1. Retrieve the Screenshot URL¶

Append queries with screenshots=1 to receive a screenshot JSON object in the response.

For example, the following Iris API queries (with header authentication) include screenshot requests.

Example Queries for Screenshot URL Retrieval¶

Iris Detect: https://api.domaintools.com/v1/iris-detect/domains/watched/?screenshots=1
Iris Enrich: https://api.domaintools.com/v1/iris-enrich/?domain=example.com&screenshots=1
Iris Investigate: https://api.domaintools.com/v1/iris-investigate/?domain=example.com&screenshots=1

Query Parameters for Screenshot URL Retrieval¶

screenshots¶

Required: yes

Type: flag (1)

Valid Values: 1

Description: Triggers screenshot object in response.

Example: screenshots=1

Response Fields for Screenshot URL Retrieval¶

ip_address¶

Type: string | null

Valid Values: IP address

Description: The IP address from which the screenshot was taken.

Example: 212.129.31.169

last_attempt¶

Type: string

Valid Values: ISO 8601 date-time format

Description: The date and time the screenshot was last attempted.

Example: 2025-02-17T15:34:55Z

last_seen¶

Type: string

Valid Values: ISO 8601 date-time format

Description: The date and time the screenshot was last observed

Example: 2025-02-17T15:34:55Z

screenshot¶

Type: object

Valid Values: JSON object

Description: Details about the screenshot.

src¶

Type: str

Valid Values: URL

Description: Link to the screenshot.

Example: https://screenshots.ne.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Fespn.com&ts=2024-03-28T21%3A48%3A37Z&token=dec12499e06b61d17175c683387307c9b751c71fbbbd797b8e094c2c288f2b31

timestamp¶

Type: string

Valid Values: ISO 8601 date-time format

Description: The date and time the provided screenshot (in fullsize field) was obtained.

Example: 2024-08-05T16:17:45Z

Response Example for Screenshot URL Retrieval¶

"screenshot": {
          "timestamp": "2025-03-07T19:53:44Z",
          "src": "https://screenshots.ar.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Fdomaintools.com&ts=2025-03-07T19%3A53%3A44Z&token=2d6269e40f4bc48908b17d218e5647fc90c0034618e39ec20806910d3909785c",
          "ip_address": "141.193.213.21",
          "last_attempt": "2025-04-07T18:00:01Z",
          "last_seen": "2025-04-07T18:00:01Z"
        }

2. Retrieve and Optionally Resize the Screenshot Image via its URL¶

Use the src URL in the returned screenshot object to download the screenshot image. The URL already contains the required parameters domain, ts, rurl, and token. Optionally add resize_width and crop_height to resize the image.

Query Parameters for Screenshot Image File¶

resize_width¶

Required: no

Type: integer

Valid Values: Width in pixels

Description: If the value is less than the width of the image, the image will be shrunk horizontally to the given resize_width, preserving the aspect ratio.

Example: resize_width=500

crop_height¶

Required: no

Type: integer

Valid Values: Height in pixels

Description: If the value is less than the height of the image, the image will be cropped vertically to the given crop_height, removing pixels from the bottom of the image.

Example: crop_height=500

Example Query for Screenshot Image File¶

api.domaintools.com/screenshot_image?domain=domaintools.com&ts=2025-04-30T14:32:10Z&resize_width=500&crop_height=500&rurl=https://www.domaintools.com/

Interpreting Screenshot Metadata¶

Use the last_attempt, last_seen, and timestamp to interpret the screenshot.

To confirm that the most recent screenshot was gathered during the current domain lifecycle—and isn't from an older, historic screenshot—compare the screenshot's timestamp with the domain's first_seen value in the API response. If the timestamp is later than first_seen, the screenshot was taken during the current domain lifecycle.

Initial capture¶

The screenshot was successfully captured during the first and only attempt. Since there have been no subsequent checks, all timestamp fields are identical.

Relationships: timestamp = last_seen = last_attempt

Response example:

        "screenshot": {
          "timestamp": "2025-05-12T14:38:19Z",
          "src": "https://screenshots.ar.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Fxumi.fr&ts=2025-05-12T14%3A38%3A19Z&token=5fbd3aa604682d26d9f1f69810a87bfd75ea25e56eadb3553cefcff2ba804f28",
          "ip_address": "76.76.21.21",
          "last_attempt": "2025-05-12T14:38:19Z",
          "last_seen": "2025-05-12T14:38:19Z"
        }

Gather attempt was duplicate of initial screenshot¶

DomainTools re-checked a domain after previously taking an initial screenshot. The result was identical to the existing image and no new screenshot was generated.

Relationships: timestamp < last_seen = last_attempt

timestamp remains unchanged, preserving the original capture time.
last_attempt is updated to reflect the most recent screenshot check.
last_seen is updated to indicate the most recent time the image was confirmed valid.
Because no new image was needed, last_seen and last_attempt are equal.

Response example:

        "screenshot": {
          "timestamp": "2025-05-12T10:10:49Z",
          "src": "https://screenshots.ar.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Fdomaintools.co.in&ts=2025-05-12T10%3A10%3A49Z&token=28d255010a09d1cc8a3326e1c1406971910293f09ddac0159eb35391f705be57",
          "ip_address": "104.219.250.192",
          "last_attempt": "2025-05-13T17:16:34Z",
          "last_seen": "2025-05-13T17:16:34Z"
        }

Recapture failed after previous successful capture¶

DomainTools successfully captured a screenshot on a previous attempt. The next attempt to capture the screenshot failed — the system was unable to retrieve a new image and could not confirm whether the content had changed.

Relationships: timestamp = last_seen, and last_seen < last_attempt

timestamp reflects the time the screenshot was originally captured.
last_seen is equal to timestamp, because that was the last time a screenshot was successfully observed
last_attempt is more recent than last_seen, but the attempt failed

Response example:

        "screenshot": {
          "timestamp": "2023-12-19T22:17:10Z",
          "src": "https://screenshots.ar.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Ffixhelpdesk.com&ts=2023-12-19T22%3A17%3A10Z&token=8cd6edb822594a0aa485e72f5cbb5414a73b657f7438b770844f46fe886c4ea9",
          "ip_address": "91.195.240.19",
          "last_attempt": "2025-05-13T10:25:04Z",
          "last_seen": "2023-12-19T22:17:10Z"
        }

Duplicate capture followed by failed attempt¶

A screenshot was captured, and subsequently re-captured as a duplicate. A subsequent attempt to refresh the (duplicate) screenshot failed.

Relationships: timestamp < last_seen, and last_seen < last_attempt

timestamp reflects the original screenshot date
last_seen is later than timestamp, indicating the image was revalidated as a duplicate on a later date
last_attempt reflects a more recent failed attempt to recapture the screenshot

Example response:

        "screenshot": {
          "timestamp": "2022-07-02T10:03:43Z",
          "src": "https://screenshots.ar.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Fdomaintools.ca&ts=2022-07-02T10%3A03%3A43Z&token=6fa06c07ff1b7206ae8f38aadaf4e11b8cf538b7625944e2813a72ebec2c6648",
          "ip_address": "158.85.87.76",
          "last_attempt": "2025-05-13T10:12:04Z",
          "last_seen": "2024-05-22T10:11:09Z"
        }

Integrating the Iris Investigate UI and the Iris Investigate API¶

The Iris Investigate Platform offers a rich UI to search and pivot through domain name data. Nearly all the data in the Iris Investigate "Pivot Engine" pane is accessible in the Iris Investigate API, and the most common research patterns can be easily accomplished with that API.

However, even with these capabilities in the API, there remains a number of scenarios where users can only meet their goals with the complete set of tools and resources offered in the Iris Investigate UI. These scenarios include:

"OR" searches, or nested "AND" and "OR" searches across multiple fields and values.
Ad-hoc investigations into a single domain's hosting, WHOIS, or screenshot history
Graph visualization and graph-initiated pivoting
Passive DNS queries on IPs and hostnames

That means users may start their investigation in the Iris Investigate UI, but then expect to bring the results of their investigation into a third-party product. The search_hash parameter in the API makes this possible. Here's how it works.

First, a user conducts an investigation in the Iris Investigate UI, potentially building a complex query to find all the connected infrastructure for a given domain name or threat actor. They access the Advanced Search in Iris Investigate and export the encoded representation of their search.

Next, the user provides this encoded string to your solution, and you craft an Iris Investigate API search with that string in the search_hash parameter. No other search parameters are required or supported (except the essential authorization parameters that should always be present). The Iris API "unpacks" the encoded search, runs the same query again, and returns the most up-to-date complete result set.

Last modified: Aug 7, 2025

Iris Investigate API Guide¶

Overview¶

Getting Started¶

API Endpoint¶

API Authentication¶

Query Limits and Testing¶

Retrieve Domain Records with a Test Query¶

Search for a Set of Domain Names¶

Use Base Search and Search Filter Parameters¶

Base Search Parameters¶

adsense¶

baidu_analytics¶

contact_name¶

contact_phone¶

contact_street¶

domain¶

email¶

email_dns_soa¶

email_domain¶

facebook¶

google_analytics¶

google_analytics_4¶

google_tag_manager¶

historical_email¶

historical_free_text¶

historical_registrant¶

hotjar¶

iana_id¶

ip¶

mailserver_domain¶

mailserver_host¶

mailserver_ip¶

matomo¶

nameserver_domain¶

nameserver_host¶

nameserver_ip¶

redirect_domain¶

registrant¶

registrant_org¶

registrar¶

search_hash¶

server_type¶

ssl_alt_names¶

ssl_common_name¶

ssl_duration¶

ssl_email¶

ssl_hash¶

ssl_issuer_common_name¶

ssl_org¶

ssl_subject¶

statcounter_project¶

statcounter_security¶

tagged_with_all¶

tagged_with_any¶

website_title¶

whois¶

yandex_metrica¶

Search Filter Parameters¶

active¶

create_date¶

expiration_date¶

first_seen_since¶

first_seen_within¶

ip_country_code¶

not_tagged_with_all¶

not_tagged_with_any¶

rank¶

risk_score¶

server_type¶

ssl_not_after¶

ssl_not_before¶

tagged_with_all¶

tagged_with_any¶

tld¶

website_title¶

Search and Filter within Parsed WHOIS and Parsed Domain RDAP Fields¶

Query Quota Consumption¶

Duplicate Query Policy for API¶

Activities That Consume Quota¶

Activities That Do Not Consume Quota¶

Use the `position` Parameter to Page Through Results¶

Use the `next` Parameter to Automatically Generate the URL for the Next Page of Results¶

Use `page_size` to Limit Page Size¶

Use `sort_by` to Sort Results by `first_seen_since`, `create_date`, `domain`, or `risk_score`¶

Use `sort_direction` to Set the Sort Direction¶