Iris Investigate: API Reference 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 more 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.

Credentials are linked to your organization's DomainTools enterprise account, which must be authorized for Iris Investigate.

Get started with Header Authentication by passing your API key in the X-Api-Key header field (example below)

Query Limits and Testing¶

Query limits are inherited from and shared with Iris Investigate UI limits.

Note

Please 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'

Default records for domaintools.com are returned 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¶

Parameter	Description	Supports WHOIS/RDAP Fields Search	Compare To
adsense	Google AdSense tracking code
baidu_analytics	Baidu analytics code
contact_name	Contact name from domain registration data	Yes
contact_phone	Contact street address from domain registration data	Yes
contact_street	Contact street address from domain registration data	Yes
domain	Apex domain
email	Email address from the most recently available WHOIS record, DNS SOA record or SSL certificate	Yes - for registration emails	Reverse WHOIS
email_dns_soa	DNS SOA email
email_domain	Apex domain portion of a WHOIS or DNS SOA email address	Yes - for registration emails	Reverse WHOIS
facebook	Facebook/Meta tracking code
google_analytics	Google Analytics tracking code
google_analytics_4	Google Analytics 4 tracking code
google_tag_manager	Google Tag Manager tracking code
historical_email	Email addresses from historical WHOIS records
historical_free_text	Free text search of a domain's historical WHOIS records - compare to `whois`
historical_registrant	Registrant names from historical WHOIS records
hotjar	Hotjar tracking code
iana_id	Registrar IANA code from most recent RDAP record for a domain
ip	IPv4 address the registered domain was last known to point to during an active DNS check		Reverse IP
mailserver_domain	Only the registered domain portion of the mail server (domaintools.net)
mailserver_host	Fully-qualified host name of the mail server (mx.domaintools.net)		Reverse MX
mailserver_ip	IP address of the mail server
matomo	Matomo tracking code
nameserver_domain	Registered domain portion of the name server (domaintools.net)		Reverse Nameserver
nameserver_host	Fully-qualified host name of the name server (ns1.domaintools.net)
nameserver_ip	IP address of the name server
redirect_domain	Find domains observed to redirect to another domain name
registrant	Substring search on the WHOIS registrant field	Yes	Reverse WHOIS
registrant_org	Substring search on the WHOIS registrant org field	Yes	Reverse WHOIS
registrar	Exact match to the WHOIS registrar field	Yes	Reverse WHOIS
search_hash	Encoded search from the Iris Investigate UI
server_type	Most recent server type retrieved from screenshot gathering
ssl_alt_names	Query elements/labels from a list of domains/subdomains in certificate Subject Alt Name lists
ssl_common_name	Certificate Common Name
ssl_duration	Certificate validity duration, in number of days
ssl_email	Email address from the SSL certificate
ssl_hash	SSL certificate SHA-1 hash
ssl_issuer_common_name	Certificate issuer Common Name
ssl_org	Exact match to the organization name on the SSL certificate
ssl_subject	Subject field from the SSL certificate
statcounter_project	Statcounter Project tracker code
statcounter_security	Statcounter Security tracker code
tagged_with_all	Domain tagged with all tags
tagged_with_any	Domains tagged with a specific Iris Tag
website_title	HTML title from most recent screenshot
whois	Free text search of a domain's most recent WHOIS record - compare to `historical_free_text`
yandex_metrica	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 .net TLD will surface domaintools.com as a result:

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

Filter	Description	Supports WHOIS/RDAP Fields Search
active	`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	Only include domains created on a specific date, in YYYY-MM-DD format	Yes
expiration_date	Only include domains expiring on a specific date, in YYYY-MM-DD format	Yes
first_seen_since	Matches domains with a first seen on or after an ISO8601-compliant date/time (including a timezone)
first_seen_within	Matches domains with a first seen within a specific number of seconds from when the request is made
ip_country_code	Country code for IP A-record
not_tagged_with_all	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	A tag or a comma-separated list of tags. Filters for domains that are not tagged with any of the provided tags.
rank	Popularity rank (replaces Alexa ranking)
risk_score	Domain Risk Score
server_type	The web server type
ssl_not_after	Validity end date for a certificate (YYYY-MM-DD)
ssl_not_before	Validity being date for a certificate (YYYY-MM-DD)
tagged_with_all	A tag or comma-separated list of tags. Filters for domain that are tagged with all of the provided tags.
tagged_with_any	A tag or a comma-separated list of tags. Filters for domains that are tagged with any of the provided tags.
tld	Limit results to only include domains in a specific top-level domain (i.e., `tld=com`, `tld=ru`)
website_title	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 Limits & Pagination¶

Too Many Results¶

Domains will only be returned if there are less than 10k 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 with >500 and <10,000 results return HTTP 200 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, but but 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:

Scenario	Sample Parameter	Expected Result
Retrieve Domains matching one of the specified Tags	`?tagged_with_any=watch,monitor`	All Domains which have been tagged as ‘watch’ OR ‘monitor’
Retrieve Domains matching a list of Tags	`?tagged_with_all=block,dangerous,evil`	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:

Scenario	Sample Parameter	Expected Result
Filter result sets by only displaying Domains matching one of the specified ‘Tags’	`?nameserver_domain=markmonitor.zone&tagged_with_any=watch,monitor`	Only list Domains which are tagged as ‘watch’ OR ‘monitor’
Filter result sets by only displaying Domains matching a List of ‘Tags’	`?nameserver_domain=markmonitor.zone&tagged_with_all=block,dangerous,evil`	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’	`?nameserver_domain=markmonitor.zone¬_tagged_with_any=watch,monitor`	Only list Domains which are not tagged with ‘watch’ or ‘monitor’
Filter result sets by excluding domains	`?nameserver_domain=markmonitor.zone¬_tagged_with_all=zerolisted,safe,trusted`	Only list Domains which are not tagged as ‘zerolisted’ and ‘safe’ and ‘trusted’
matching a List of ‘Tags’	–	–

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¶

Query Parameter	Required	Type	Valid Values	Description	Example
`screenshots`	yes	flag (1)	`1`	Triggers screenshot object in response.	`screenshots=1`

Response Fields for Screenshot URL Retrieval¶

Output field	Type	Valid Values	Description	Example
`ip_address`	string \| null	IP address	The IP address from which the screenshot was taken.	`212.129.31.169`
`last_attempt`	string	ISO 8601 date-time format	The date and time the screenshot was last attempted.	`2025-02-17T15:34:55Z`
`last_seen`	string	ISO 8601 date-time format	The date and time the screenshot was last observed	`2025-02-17T15:34:55Z`
`screenshot`	object	JSON object	Details about the screenshot.
`src`	str	URL	Link to the screenshot.	`https://screenshots.ne.domaintools.com/screenshot_image?s3v=1&rurl=http%3A%2F%2Fespn.com&ts=2024-03-28T21%3A48%3A37Z&token=dec12499e06b61d17175c683387307c9b751c71fbbbd797b8e094c2c288f2b31`
`timestamp`	string	ISO 8601 date-time format	The date and time the provided screenshot (in `fullsize` field) was obtained.	`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¶

Query Parameter	Required	Type	Valid Values	Description	Example
`resize_width`	no	integer	Width in pixels	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.	`resize_width=500`
`crop_height`	no	integer	Height in pixels	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.	`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 Reference 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¶

Search Filter Parameters¶

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

Query Limits & Pagination¶

Too Many Results¶

Paginated Results¶

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¶

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

Use Domain Tags as a Base Search or Filter Parameter¶

Use Domain Tags as a Search Parameter¶

Use Domain Tags as a Search Filter¶

Guided Pivots with the Iris Investigate API¶

Monitoring newly active domains with the Iris Investigate API¶

Retrieve Screenshots¶

1. Retrieve the Screenshot URL¶

Example Queries for Screenshot URL Retrieval¶

Query Parameters for Screenshot URL Retrieval¶

Response Fields for Screenshot URL Retrieval¶

Response Example for Screenshot URL Retrieval¶

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

Query Parameters for Screenshot Image File¶

Example Query for Screenshot Image File¶

Interpreting Screenshot Metadata¶

Initial capture¶

Gather attempt was duplicate of initial screenshot¶

Recapture failed after previous successful capture¶

Duplicate capture followed by failed attempt¶

Integrating the Iris Investigate UI and the Iris Investigate API¶

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¶