Summarize Requests¶

Summarize requests return a summary of RRsets that would be returned by a lookup query. This gives you an estimate of result size and provides at-a-glance information on when a given domain name, IP address, or other DNS asset was first-seen and last-seen by the global sensor network, as well as the total observation count.

URL Path Scheme¶

All DNSDB summarize requests are rooted in URL paths under the /dnsdb/v2/summarize hierarchy. Everything underneath /dnsdb/v2/summarize is the same as for /dnsdb/v2/lookup queries:

/dnsdb/v2/summarize/rrset/name/OWNER_NAME/RRTYPE/BAILIWICK
/dnsdb/v2/summarize/rdata/TYPE/VALUE/RRTYPE

Query Parameters¶

Summarize requests accept the same optional query parameters as lookup requests, with one additional parameter:

Parameter	Description
max_count	Controls stopping when the summary count reaches this value. 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.

See Query Parameters for all other available parameters.

Result Format¶

The DNSDB API only supports one Summarize result format, the "jsonl" format (though this should be specified in an HTTP ACCEPT header as 'application/x-ndjson').

RRset and Rdata Results¶

Key	Description
count	The number of times the RRset was observed via passive DNS replication.
num_results	The number of results (RRsets) that would be returned from a Lookup.
time_first, time_last	UNIX epoch timestamps with second granularity indicating the first and last times the RRset was observed via passive DNS replication. Only present if the RRsets were observed via passive DNS replication.
zone_time_first, zone_time_last	UNIX epoch timestamps with second granularity indicating the first and last times the RRset was observed via zone file import. Only present if the RRsets were observed via zone file import.

Examples¶

Example 1: Basic Summarize¶

An example JSON object:

{"count":528,"num_results":4,"time_first":1557864746,"time_last":1560524861}

As encapsulated by the SAF, this would be expressed on the wire as:

{"cond":"begin"}
{"obj":{"count":528,"num_results":4,"time_first":1557864746,"time_last":1560524861}}
{"cond":"succeeded"}

Example 2: No Results Found¶

If there are no RRsets found by the underlying query, the DNSDB API will return:

{"count":0, "num_results":0}

As encapsulated by the SAF:

{"cond":"begin"}
{"obj":{"count":0,"num_results":0}}
{"cond":"succeeded"}

Example 3: Summarize with limit and max_count¶

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/summarize/rrset/name/www.farsightsecurity.com\
  ?limit=2&max_count=5000"

In this call, the summarize processing will limit itself to looking at two underlying results rows and will stop when the count value reaches max_count. Since the first row exceeds max_count, the summarize will only account for the first row.

Response:

{"cond":"succeeded","obj":{"count":1127,"num_results":2,"time_first":1557859313,
  "time_last":1560537333}}

Example 4: Summarize with only limit¶

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/summarize/rrset/name/www.farsightsecurity.com?limit=2"

In this call, the summarize processing will limit itself to looking at two underlying results rows. The count is the sum of the counts from the two rows, and the time_first is from the first row while time_last is from the second row.

Response:

{"cond":"succeeded","obj":{"count":1127,"num_results":2,"time_first":1557859313,
    "time_last":1560537333}}

Example 5: Summarize with only max_count¶

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/summarize/rrset/name/www.farsightsecurity.com\
  ?max_count=50000"

Response:

{"cond":"succeeded","obj":{"count":1078,"num_results":2,"time_first":1573594176,
    "time_last":1576187607}}

Example 6: Summarize IP network¶

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/summarize/rdata/ip/104.244.13.104,29"

Response:

```json {"cond":"succeeded","obj":{"count":528,"num_results":4,"time_first":1557864746, "time_last":1560524861}}