Monitor 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.

How It Works

This can be accomplished by adding either first_seen_since or first_seen_within to the API query. The first seen is the date/time (in UTC) that DomainTools discovers a domain as newly active.

Implementation Considerations

Basic Monitoring Pattern

Track newly active domains by storing the timestamp of your last query and using it in subsequent requests:

# Store last query time
last_check = "2024-02-04T10:00:00Z"

# Query for new domains since last check
query = f"?ip=199.30.228.112&first_seen_since={last_check}"

# Process results...

# Update timestamp for next query
last_check = current_timestamp

Choosing Time Parameters

Use the appropriate parameter based on your monitoring frequency:

first_seen_within: Rolling time window in seconds
- Example: first_seen_within=3600 for “domains discovered in the last hour”
- Updates automatically with each query
- Best for regular polling intervals
first_seen_since: Exact timestamp in ISO8601 format
- Example: first_seen_since=2024-02-04T10:00:00Z
- Requires storing and updating the timestamp
- Best when you need to track precise query windows

Handling Large Result Sets

Monitor queries can return large datasets. Plan accordingly:

Pagination: Results exceeding 500 domains require pagination. Check has_more_results in the response and use the position parameter to retrieve additional pages. Each page retrieval counts against quota.

10,000 Result Limit: Queries matching more than 10,000 domains return error code 413. Narrow your monitoring criteria with additional filters:

# Too broad - may exceed 10,000
?nameserver_domain=markmonitor.zone&first_seen_within=86400

# Narrowed with TLD and risk score filters
?nameserver_domain=markmonitor.zone&tld=com&risk_score=69&first_seen_within=86400

Consider splitting broad monitoring into multiple queries with different filter combinations.

Quota Optimization

Identical queries within 1 hour do not consume additional quota. For frequent monitoring:

Query every 15 minutes with first_seen_within=3600
Only the first query each hour counts against quota
Subsequent identical queries return cached results

This allows frequent checks without excessive quota consumption.

Use Cases

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.

Examples

Monitor Domains on a Specific IP

Monitor for newly active domains on IP 199.30.228.112 discovered in the last 24 hours:

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

Monitor Domains with Specific SSL Certificate

Monitor for newly active domains using a specific SSL certificate hash:

https://api.domaintools.com/v1/iris-investigate/?ssl_hash=abc123def456&first_seen_since=2024-01-01T00:00:00Z

Monitor Domains on Nameserver with TLD Filter

Monitor for newly active .com domains on a specific nameserver:

https://api.domaintools.com/v1/iris-investigate/?nameserver_domain=example.com&tld=com&first_seen_within=3600