Other Query Parameters¶
In addition to time-fencing parameters, DNSDB supports several other optional query parameters that control result behavior and metadata.
Common Parameters¶
The following optional parameters may be present in lookup and summarize query URLs:
| Parameter | Description |
|---|---|
| limit | Limit for the number of results returned via these lookup methods. There is a built-in limit to the number of results that are returned via these lookup methods. The default limit is set at 10,000. This limit can be raised or lowered by setting the "limit" query parameter. There is also a maximum number of results allowed; requesting a limit greater than the maximum will only return the maximum. See results_max below for information on that maximum. If "?limit=0" is used then DNSDB will return the maximum number of results allowed. Obviously, if there are less results for the query than the requested limit, only the actual amount can be returned. Example: appending "?limit=20000" to the URL path will set the response limit to 20,000 results. |
| swclient | Name of the API client software generating the DNSDB query. Limited to twenty alphanumeric characters. This may be logged by the DNSDB API server. Farsight support can help you debug a new API client using this and the following parameter. There is no default. Example: "?swclient=dnsdbq". |
| version | Version number of the API client software generating the DNSDB query. Limited to twenty alphanumeric characters plus dash, underscore, and period. This may be logged by the DNSDB API server. There is no default. Example: "?version=1.1a". |
| id | Client software specific identity of the user of the API client. Comprised of an alphanumeric string, a colon, and an alphanumeric string, limited to thirty characters. This may be logged by the DNSDB API server. There is no default. Example: "?id=dnsq:91e6245ad31387". |
| aggr | Aggregated results group identical rrsets across all time periods and is the classic behavior from querying the DNSDB. This means you could get the total number of times an rrset has been observed, but not when it was observed. Unaggregated results ungroup identical rrsets, allowing you to see how the domain name was resolved in the DNS across the full-time range covered in DNSDB (subject to time fencing). This can give a more accurate impression of record request volume across time because it will reveal the distinct timestamps of records whose values are repeated. You can answer questions like, "Was a domain parked for a long time, mostly unused, until it was repurposed for serving malware or relaying spam, but then was abandoned again?" It allows you to see if a record was observed heavily in the last week vs. having been observed constantly for years. This is a boolean value. Use True, the default, for the aggregated results or False for unaggregated results. The value is case insensitive and can be abbreviated. Example: "?aggr=f". |
| humantime | A boolean value that is True if time values (in time_first, time_last, zone_time_first, zone_time_last) should be returned in human readable (RFC3339 compliant) format or False if Unix-style time values in seconds since the epoch should be returned. False is the classic behavior from querying the DNSDB and is the default value for this option. The value is case insensitive and can be abbreviated. Example: "?humantime=t". |
Lookup-Specific Parameter¶
The following optional parameter may be present in a lookup query URL:
| Parameter | Description |
|---|---|
| offset | How many rows to offset (e.g. skip) in the results. This implements an incremental result transfer feature, allowing you to view more of the available results for a single query. The rows are offset prior to the limit parameter being applied, therefore offset allows seeing additional results past a limit that matches the maximum number of results. Note that DNSDB recalculates the results for each query and the order of results might not be preserved. Therefore, this capability is not a valid way to walk all results over multiple queries -- some results might be missing and some might be duplicated. The actual offset that can be used is limited or for certain API keys, offset is not allowed -- see the offset_max rate_limit key below. The offset value must be a positive integer. The default is 0, which means do not offset the rows. Example to return the second million results (assuming results_max is 100000): "?limit=100000&offset=1000000". |
Summarize-Specific Parameter¶
The following optional parameter may be present in a summarize query URL:
| Parameter | Description |
|---|---|
| max_count | max_count controls stopping when we reach that summary count. The resulting total count can exceed max_count as it will include the entire count from the last rrset examined. The default is to not constrain the count. Example: appending "?max_count=100" to the URL path will stop the summary when its total count reaches 100. |
Usage Examples¶
Limit results to 100¶
curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
"https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?limit=100"
Use unaggregated results¶
curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
"https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?aggr=false"
Return human-readable timestamps¶
curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
"https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?humantime=true"
Combine multiple parameters¶
curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
"https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com\
?limit=1000&aggr=f&humantime=t&swclient=myclient&version=1.0"
Use offset for pagination¶
# First page
curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
"https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?limit=1000"
# Second page
curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
"https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?limit=1000&offset=1000"
Offset Limitations
The offset parameter is not a reliable way to walk all results over multiple queries because DNSDB recalculates results for each query and the order might not be preserved. Some results might be missing and some might be duplicated.