Subdomain enumeration
Usage
This endpoint returns distinct subdomain names from Profundis's DNS observations. Set only_resolving: true to receive only names verified by DNS within the last 24 hours. You can also use Only resolving · Live in the web UI and download the results as CSV, JSON or TXT.
The personal API requires a paid subscription or unused purchased credits. A Free account's monthly allocation alone does not grant API access. See API usage and Generate a token.
How do I send a request?
Send a POST request to https://api.profundis.io/api/v2/common/data/subdomains. Replace the key and domain in this example:
API_KEY='YOUR_API_KEY'
curl "https://api.profundis.io/api/v2/common/data/subdomains" \
-H "X-API-KEY: $API_KEY" \
-H "Accept: text/event-stream" \
-H "Content-Type: application/json" \
-N \
-X POST \
-d '{
"domain": "example.com",
"max_credits": 3
}'
| Field | Meaning |
|---|---|
domain | Required domain name, such as example.com. You can use api.example.com to look for names beneath that subdomain. Do not include *., a URL scheme or a path. |
only_resolving | Optional boolean, default false. Enables Live DNS verification; requires a paid subscription or a positive PAYG balance. NXDOMAIN, DNS errors and names that could not be verified are excluded. |
max_credits | Optional integer spending limit for this request, from 1 to 100000. Omit it or set it to 0 for no request-specific limit; your available credits still apply. |
source | Optional label identifying the caller in request logs. It does not change billing or access. |
Malformed JSON, unknown fields, an invalid domain or an out-of-range max_credits returns HTTP 400 before enumeration starts.
How does Live work?
Use {"domain":"example.com","only_resolving":true,"max_credits":3} to verify the indexed names. Live checks the entire inventory without a verification count limit. Results stream progressively; a large uncached inventory can take longer than ten seconds to finish. Positive and negative DNS outcomes are cached for 24 hours, shared across lookups. Reading a cached result does not extend its expiry.
If the inventory is empty, Profundis Recon uses names ranked from previous successful Recon campaigns. Live runs the same discovery when no indexed name is confirmed, for example when every indexed name has stopped resolving. This discovery takes at most 20 seconds; pending checks continue in the background. Verification also continues if you stop reading or reach your spending limit. A later lookup reuses the completed checks.
Paid and PAYG requests also try this fast discovery when the inventory is empty without Live. Every served lookup schedules a background DNS refresh, subject to domain deduplication. In the Free web UI, an empty lookup returns promptly and schedules discovery; repeat the lookup after the background refresh. Empty inventories are not cached. Recent discoveries can be returned before they appear in the search index.
A registered domain can have no qualifying subdomains. An empty response therefore remains possible. Ordinary enumeration can include historical names that no longer resolve; enable Live when current resolution matters.
How much does it cost?
The endpoint charges 1 credit per batch of up to 100 names for the first 300, then 1 credit per batch of up to 300 names beyond that. A final partial batch also costs 1 credit. A successful enumeration costs at least 1 credit, even when no names are found.
For example, 100 names cost 1 credit, 300 cost 3, and 600 cost 4. Charges happen before each batch is sent. See Credits.
Live uses the same pricing, based on the names delivered. If verification fails before any name is delivered, that failed Live request is not charged. Background refresh does not add another user charge.
The example's max_credits: 3 allows at most 3 credits to be charged. If more names remain, enumeration stops before charging the next batch. The ceiling is not a charge made in advance.
How do I read the response?
A started enumeration returns HTTP 200 with Content-Type: text/event-stream; charset=utf-8. Its body is a newline-delimited stream, not a JSON array or standard SSE data: frames. Read it line by line with a streaming HTTP client; curl -N disables output buffering.
- Plain text lines are subdomain names, in lowercase and without duplicates.
- JSON lines with
"type":"credits"report the account's credit state after charged batches and at stream end. They are control messages, not subdomains. - JSON lines with
"type":"enumeration"report Live coverage and automatic discovery. They are also control messages. - JSON lines with
"type":"heartbeat"keep an ongoing verification stream active; ignore them when collecting names. - JSON lines with
codeandmessage,errorornoticedescribe an error or limit. Keep them separate from the names you collect.
The credits object contains monthly_credits, credits_used, balance and cycle_end. A snapshot can be omitted if it cannot be loaded. When you set a positive max_credits, the final credits control line also reports credits_charged: the actual cost of this request. If that ceiling stops the list, it includes capped: true and max_credits.
For example, if more than 300 names are available and the ceiling of 3 credits stops enumeration, the final credits control line includes:
{
"type": "credits",
"credits_charged": 3,
"capped": true,
"max_credits": 3
}
The account's credits snapshot is omitted from this example for brevity. If the ceiling is not reached, capped and max_credits are absent. A credit error can follow the final credits line, so read the entire response.
Frequent questions
Why are there fewer results than in DNS search?
The DNS search shows individual DNS observations, including different record types, values and dates for the same host. Enumeration returns each matching name only once, without its DNS values or history. A credit balance or request spending limit can also stop the list early. Neither view guarantees a complete live inventory.
Does the Free plan's 300-name limit apply to this API?
The 300-name limit applies to web UI enumeration by a Free account without unused purchased credits. Personal API calls require the paid subscription or purchased balance described above; qualifying calls do not have that Free-plan cap. They remain bounded by available credits and any max_credits you set.
What happens when I run out of credits?
There are two cases:
- Before the stream starts: no spendable credits, or no qualifying API access, returns HTTP
402with a JSON error containingcode: "Q2014"and a human-readablemessage. Enumeration does not start and nothing is charged. - After the stream starts: if the next batch cannot be paid for, the response remains HTTP
200and ends with a JSON error line containingcode: "Q2014". Names already sent remain usable, and the batches already delivered remain charged. Treat the list as incomplete.
Use the status and code in your integration rather than matching the wording of message. Q2014 identifies a credit or API-access block, not a daily or monthly search-quota counter. Buy a credit pack or, for a paid subscription's exhausted allocation, wait for its next cycle. Renewing a Free monthly allocation does not restore API access without purchased credits or a paid subscription.
A self-set usage guard can also stop a charge even when credits remain. Its error code is Q2015; wait for the guard's window to reset or adjust the limit in your profile. This is separate from the per-request max_credits ceiling, which is reported by capped: true rather than a credit error.
How do I detect incomplete Live results?
Read the entire stream, including its enumeration control line:
{"type":"enumeration","only_resolving":true,"partial":false,"recon_queued":true,"fast_recon":false}
partial: true means verification is incomplete, for example after a DNS failure or an interrupted discovery response. It does not mean that the omitted names do not resolve. fast_recon reports completion of a fast discovery attempt, even if it found no names. recon_queued means a refresh was newly queued or is still pending; recent work can suppress a duplicate refresh. This control line can also accompany ordinary enumeration.
If a downstream service is unavailable, Live still returns HTTP 200, with partial: true and no technical error line. Already returned names remain verified; unverified historical names are never substituted. An incomplete Live response with no verified names costs zero credits. A Free web UI request that tries to enable Live receives HTTP 403 with LIVE_REQUIRES_PAID. Free personal API access remains subject to the HTTP 402 gate described above.