Skip to content
DomainTools Technical Documentation

Farsight DNSDB API

Download PDF

Build our world-class domain intelligence into your own tools.

This guide will help you get started with the DNSDB API v2. Prefer a GUI? See the Scout web and desktop app.

What is DNSDB?

Section titled “What is DNSDB?”

DNSDB is a database that stores and indexes both the passive DNS data available via Farsight Security’s Security Information Exchange as well as the authoritative DNS data that various zone operators make available. DNSDB makes it easy to search for individual DNS RRsets and provides additional metadata for search results such as first seen and last seen timestamps as well as the DNS bailiwick associated with an RRset.

API Versions

Section titled “API Versions”

There are two versions of the API:

  • API v1: Legacy version (see API v1 Reference)
  • API v2: Current version (documented here)

Key Differences in API v2

Section titled “Key Differences in API v2”
  • Results are encapsulated in Streaming API Framing (SAF) Protocol
  • Only “jsonl” output format is supported (specified as ‘application/x-ndjson’)
  • All API URLs now start with /dnsdb/v2
  • The rate_limit request moved to /dnsdb/v2/rate_limit
  • Rdata values are always returned as an array
  • Improved error handling and status codes

Quick Start

Section titled “Quick Start”

1. Set Up Authentication

Section titled “1. Set Up Authentication”

Set your API key as an environment variable:

export DNSDB_API_KEY="your-api-key-here"

See Authentication for more details.

2. Check Your Quota

Section titled “2. Check Your Quota”

Before making queries, check your available quota:

curl -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/rate_limit"

See Rate Limits for more information.

3. Make Your First Query

Section titled “3. Make Your First Query”

Lookup all RRsets for a domain:

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=10"

Core Concepts

Section titled “Core Concepts”

Request Types

Section titled “Request Types”

DNSDB supports four types of requests:

  1. Lookup - Primary query to search for individual DNS RRsets

  2. Summarize - Returns a summary of RRsets that would be returned by a lookup query

  3. Ping - End-to-end connectivity test (no API key required)

  4. Rate Limit - Returns quota information

Query Parameters

Section titled “Query Parameters”

Enhance your queries with optional parameters:

Common Query Patterns

Section titled “Common Query Patterns”

Name → Answers

Section titled “Name → Answers”

Get all historical answers for a domain:

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

IP → Names

Section titled “IP → Names”

Find all names pointing to an IP:

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

Wildcard Searches

Section titled “Wildcard Searches”

Enumerate subdomains:

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

Understanding Results

Section titled “Understanding Results”

Streaming API Framing (SAF)

Section titled “Streaming API Framing (SAF)”

All lookup and summarize results are wrapped in SAF protocol:

{"cond": "begin"}
{"obj":{...result data...}}
{"obj":{...result data...}}
{"cond": "succeeded"}

The final cond value indicates success:

  • "succeeded" - Query completed successfully
  • "limited" - Result limit reached
  • Other values indicate errors or truncation

See Streaming Protocol for details.

Result Metadata

Section titled “Result Metadata”

Each result includes:

  • count: Number of times observed
  • time_first/time_last: First and last observation timestamps
  • rrname: Owner name
  • rrtype: Record type
  • rdata: Record data (always an array)
  • bailiwick: DNS zone context (rrset lookups only)

Next Steps

Section titled “Next Steps”

Getting Help

Section titled “Getting Help”