DNSDB 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
Section titled “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
Section titled “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.,
-31536000for one year ago)
Examples
Section titled “Examples”Absolute Time (Unix Timestamps)
Section titled “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)
Section titled “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
Section titled “Combining Time Parameters”You can combine multiple time parameters to create specific time ranges.
Records Only Observed in 2015
Section titled “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
Section titled “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
Section titled “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
Section titled “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 |