activedns

activedns

Python client for the ActiveDNS API: DNS search by domain, address, network and AS number. Python 3.10 or later.

pip install activedns

from activedns import Client

# name your program: it is sent in the User-Agent of every request
with Client("mytool/1.0") as client:
    page = client.query("*.example.com")
    for record in page.records:
        print(record.domain, record.ip_address, record.observed)

A query is a domain (example.com), a wildcard (*.example.com), an address, a network (192.0.2.0/24) or an AS number (AS13335). query_combined matches several at once.

query returns one page of the result and tells you whether there is more; see Paging.

It works without an account or a key. AS-number and combined searches, wider networks, complete answers and higher rates come with a token of your own.

Paging

A query returns one page: up to 100 records, or as many as page_size asks for. The page tells you whether that was everything:

The client never fetches further pages by itself. Each one is a request against your rate limit, so how much of a large result to retrieve is your decision, made with next_page:

page = client.query("*.example.com")
fetched = 0
while page is not None:
    use(page.records)
    fetched += len(page.records)
    if fetched >= 500:  # enough for this job
        break
    page = client.next_page(page)

next_page repeats the query from where the page ended, and returns None after the last page. Past the depth your token may page to, it raises ForbiddenError.

Your own token

The SDK works the moment you install it, because it carries a token of its own. That token is shared by everyone who uses the SDK, so it is deliberately modest. A token issued to you opens up considerably more of the database, and using one is a single argument:

client = Client("mytool/1.0", token=os.environ["ACTIVEDNS_TOKEN"])

Nothing else in your code changes: the same query, query_combined and next_page, with more allowed.

What a token of your own gives you

The right-hand column is where tokens start, not where they end: every token has its own limits on the server, set for what its holder is building. The numbers are those of October 2026.

What that makes possible

Map an organisation by its AS number. Every name seen resolving into a network operator's address space, without knowing a single domain beforehand:

page = client.query("AS64496")

Ask precise questions. What does this company host at that provider? Which names under a domain sit in one particular network? A combined search answers in one request what would otherwise be thousands of records to download and filter yourself:

page = client.query_combined(domain="*.example.com", asn=64496)
page = client.query_combined(domain="*.example.com", ip="192.0.2.0/24")

Sweep whole networks. A /16 in one search instead of 256 separate /24s:

page = client.query("198.51.0.0/16")

Get the whole answer. The built-in token shows the first 200 records of a search, which is enough to look around. Large zones, hosting ranges and CDNs have tens of thousands; with your own token next_page keeps going, 1,000 records at a time if you ask for pages that size:

# every name under a large zone, not only the first 200 records
names = set()
page = client.query("*.example.com", page_size=1000)
while page is not None:
    names.update(record.domain for record in page.records)
    page = client.next_page(page)
print(len(names), "names")

With the built-in token the same loop ends after 200 records with a ForbiddenError: 403: cursor beyond your token's limit of 100.

Run it where your work runs. The built-in token's allowance belongs to a network address, so an office, a cloud region or a CI provider's address range shares it with whoever else is there. Your own token's allowance is yours wherever it is used: pipelines, scheduled jobs and several machines at once. Keep the token out of the code and hand it to the job as a secret:

# GitHub Actions
- run: python -m asset_monitor
  env:
    ACTIVEDNS_TOKEN: ${{ secrets.ACTIVEDNS_TOKEN }}

Stay fast when the service is busy. Searches are served by priority. The website comes first, issued tokens next, and the tokens shared by tools and SDKs last.

When you have outgrown the built-in token

The API tells you. A search the built-in token may not make raises a ForbiddenError that says what was missing:

403: query type asn is not allowed for your token
403: combined queries (domain AND ip AND asn) are not allowed for your token
403: IPv4 network too wide for your token: prefix must be /24 or longer
403: cursor beyond your token's limit of 100; narrow the query instead

A RateLimitError whose exceeded is address or network on work you run regularly means the same thing.

Getting one

Write to us through activedns.net/contact and say what you are building and roughly how much you expect to query. Tokens are issued by hand, with limits to fit: a research project, an integration in your product and a security team's daily monitoring need different things.

About the built-in token

It identifies the SDK to the API, whatever User-Agent a request has, and it is not a secret. It allows domain, wildcard (*.example.com), address and network searches within the limits in the table above. Its rate limit counts per network address (an IPv4 address, an IPv6 /64), with a second, larger one for the network around it (IPv4 /24, IPv6 /48), so that the users of the SDK do not spend each other's allowance.

Say who you are

Client takes the name and version of your program and refuses to work without one. Requests then carry

User-Agent: mytool/1.0 activedns-py/0.1.0 (python 3.12.3; linux)

Everyone using the SDK's token looks the same to the API otherwise. With a name, a tool that misbehaves can be told apart from the rest, and its author asked about it instead of everyone being limited.

Examples

Three small programs in examples/, each one file that runs as it is:

python examples/query.py example.com                 one page of a search, and the rate limit
python examples/query.py --limit 10 192.0.2.0/24
python examples/subdomains.py --pages 5 example.com  names under a domain, paging with next_page
python examples/combined.py --domain '*.example.com' --asn 64496

They use the SDK's own token; set ACTIVEDNS_TOKEN to use yours. combined.py needs one, and shows the refusal without it; query.py with your own token also takes AS numbers (AS64496) and wider networks.

Errors

Every error is an ActiveDNSError:

from activedns import RateLimitError

try:
    page = client.query("*.example.com")
except RateLimitError as err:
    # err.exceeded: "address", "network" or "token"
    # err.retry_at: when to try again
    ...

A fair client

The API is shared, so the client holds itself back without being asked:

Share one Client across a program: these limits are kept per client. client.rate_limits holds the limits the server reported with its latest response.

Options

Records, pages and rate limits are immutable attrs classes.

Development

pip install -e '.[dev]'
pytest                  unit tests, against a fake server
ruff check .
ruff format --check .
mypy
pytest e2e              about ten requests to the live API, with the SDK's own token

The same checks run in GitHub Actions on every push and pull request (.github/workflows/ci.yml): lint and types, the unit tests on Python 3.10 to 3.14, and then the end-to-end tests against the built wheel.