Time-Fencing Query Parameters¶

DNSDB records when a specific DNS record was first and last observed. You can filter results by time using time-fencing query parameters.

Supported Parameters¶

Parameter	Description
time_first_before	Provide results before the defined timestamp for when the DNS record was first observed.
time_first_after	Provide results after the defined timestamp for when the DNS record was first observed.
time_last_before	Provide results before the defined timestamp for when the DNS record was last observed.
time_last_after	Provide results after the defined timestamp for when the DNS record was last observed.

Time Format¶

Time values must be specified as:

Unix/Epoch timestamp: Integer with seconds granularity (e.g., 1420070400)
Relative time: Negative integer representing seconds in the past (e.g., -31536000 for one year ago)

Examples¶

Absolute Time (Unix Timestamps)¶

Filter for records first observed before January 1, 2015:

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?time_first_before=1420070400"

Filter for records last observed before 2013:

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?time_last_before=1356998400"

Relative Time (Seconds in the Past)¶

Filter for records first observed within the last year:

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?time_first_after=-31536000"

Filter for records last observed within the last 31 days:

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?time_last_after=-2678400"

Combining Time Parameters¶

You can combine multiple time parameters to create specific time ranges.

Records Only Observed in 2015¶

Combine time_first_after and time_last_before to get records where both first and last observation occurred in 2015:

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?time_first_after=1420070399&time_last_before=1451606400"

Old Records Recently Observed¶

Get records first observed before 2012 but last observed within the last month (long-lived records that are still active):

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?time_first_before=1325376000&time_last_after=-2678400"

Important Notes¶

The DNSDB API server may have API key-dependent time-fencing restrictions
These restrictions cannot be expanded with query parameters but can be used to narrow the time ranges
Query parameters can completely override default time ranges if permitted by your API key
All timestamps use seconds granularity
Relative times must be preceded by a minus sign (-)

Common Time Values¶

For reference, here are some common relative time values:

Duration	Seconds	Parameter Value
1 hour	3,600	`-3600`
1 day	86,400	`-86400`
1 week	604,800	`-604800`
31 days	2,678,400	`-2678400`
1 year	31,536,000	`-31536000`