Working with screenshots in Iris APIs

Retrieve the most recent screenshot for a given domain with Iris APIs in a two-step process:

1. Retrieve the screenshot image URL
2. Retrieve and optionally resize the image file

Also consult the section on interpreting screenshot metadata.

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"
        }

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"
        }