Developer Reference

Subdomain Finder

DomScan API: No. This is best-effort passive coverage. Internal names and public hosts missing from the source datasets will not appear, and DNS verification does not search for additional names.

Subdomain Finder

No. This is best-effort passive coverage. Internal names and public hosts missing from the source datasets will not appear, and DNS verification does not search for additional names.

Use GET /v1/subdomains?domain=example.com&sources=ct. The ct value selects the compatibility pipeline, while each entry reports its actual evidence source. Cache-only misses return 202 and all-source failures return 503; both refund credits.

GET /v1/subdomains

Query Parameters

Parameter	Type	Description
domain required	string	Root domain to find subdomains for (e.g., "github.com")
prefer_cache optional	boolean token	Serve cached results only. If no fresh or stale cache exists, the API returns 202, queues a background refresh, and refunds the request credits. Accepted values: true, false, 1, 0, yes, and no. Default: false.
sources optional	string	Compatibility selector. Only `ct` is accepted. It starts the passive discovery pipeline, but each result reports the provider that supplied its evidence: `crtsh`, `crtname`, `hackertarget`, `threatminer`, `wayback`, or `certspotter`. Older cached entries may report `ct`.
verify optional	boolean token	Check DNS only for the names already selected for the response. Verification does not discover more names. Accepted values: `true`, `false`, `1`, `0`, `yes`, and `no`. Default: `false`.
include_wildcards optional	boolean token	Return wildcard certificate evidence in a separate `wildcards` array. Wildcards are not mixed into concrete hostname results. Accepted values: `true`, `false`, `1`, `0`, `yes`, and `no`. Default: `false`.
limit optional	integer	Maximum concrete hostname entries to return. Enter an integer from 1 through 2000. Default: 500.

Use Cases

Attack surface mapping and security audits
Review possible forgotten or shadow IT hostnames
Pre-acquisition technical due diligence
Competitive analysis of infrastructure
Bug bounty reconnaissance

Response Fields

Field	Description
`subdomains[].name`	Returned hostname. The apex can appear when a source includes it.
`subdomains[].source`	Review public hostname evidence with clear source labels
`subdomains[].first_seen`	CT-backed entries report the earliest certificate not-before value found. Passive fallback entries can return null.
`subdomains[].verified`	True only when verify is enabled and DNS resolution succeeds for the returned hostname. Otherwise false.
`subdomains[].dns_records`	A and CNAME records from optional verification of the returned hostname, or null. This field does not add names to the result.
`summary.total_found`	Total concrete hostname entries found before the response limit, including the apex when a source includes it.
`summary.verified_count`	Number of returned hostnames that resolved during optional DNS verification.

HTTP Status Codes

HTTP Status Codes	Description
`200` OK	Request successful
`202` Accepted	Cache-only subdomain miss accepted for background refresh. No credits are charged; retry after the Retry-After delay.
`400` Bad Request	Invalid parameters
`402` Payment Required	Not enough credits to run this request.
`503` Service Unavailable	Upstream service unavailable or temporarily rate limited.
`504` Gateway Timeout	Upstream lookup timed out.

Example Request

curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/subdomains?domain=example.com&sources=ct&include_wildcards=yes&limit=100"

curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/subdomains?domain=example.com&sources=ct&verify=yes&limit=50"

curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/subdomains?domain=example.com&prefer_cache=1"

import requests

domscan = requests.Session()
domscan.headers.update({"X-API-Key": "your-api-key"})

response = domscan.get(
    "https://domscan.net/v1/subdomains",
    params={
        "domain": "example.com",
        "sources": "ct",
        "verify": "yes",
        "include_wildcards": "yes",
        "limit": 100
    }
)
data = response.json()

print(f"Returned {data['summary']['returned']} hostname entries")
print(f"Verified: {data['summary']['verified_count']}")

live_subs = [s for s in data['subdomains'] if s['verified']]
for sub in live_subs[:10]:
    print(f"  {sub['name']}")

const domscanFetch = (url, options = {}) =>
  fetch(url, {
    ...options,
    headers: { ...options.headers, "X-API-Key": "your-api-key" },
  });

const response = await domscanFetch(
  'https://domscan.net/v1/subdomains?' + new URLSearchParams({
    domain: 'example.com',
    sources: 'ct',
    verify: 'yes',
    include_wildcards: 'yes',
    limit: '100'
  })
);
const data = await response.json();

console.log(`Returned ${data.summary.returned} hostname entries`);
console.log(`Verified: ${data.summary.verified_count}`);

data.subdomains
  .filter(s => s.verified)
  .forEach(s => console.log(`  ${s.name}`));

Example Response

{
  "domain": "example.com",
  "subdomains": [
    {
      "name": "api.example.com",
      "source": "crtsh",
      "first_seen": "2025-01-15T00:00:00Z",
      "verified": true,
      "dns_records": {
        "A": ["192.0.2.10"],
        "CNAME": null
      }
    }
  ],
  "wildcards": [
    {
      "pattern": "*.example.com",
      "source": "crtsh",
      "first_seen": "2024-11-20T00:00:00Z"
    }
  ],
  "summary": {
    "total_found": 1,
    "returned": 1,
    "verified_count": 1,
    "unverified_count": 0,
    "sources_used": ["crtsh"],
    "apex_included": false,
    "wildcard_suppressed_count": 1,
    "wildcard_returned_count": 1
  },
  "intelligence_summary": {
    "data_sources": ["crtsh"],
    "source_count": 1,
    "cache_status": "live",
    "returned_count": 1,
    "total_found": 1,
    "truncated": false,
    "limit": 100,
    "verification_requested": true,
    "include_wildcards": true,
    "verified_count": 1,
    "verified_ratio": 1,
    "live_dns_record_count": 1,
    "apex_included": false,
    "wildcard_suppressed_count": 1,
    "wildcard_returned_count": 1,
    "first_seen_oldest": "2025-01-15T00:00:00Z",
    "first_seen_newest": "2025-01-15T00:00:00Z",
    "warning_count": 0
  },
  "meta": {
    "query_time_ms": 184,
    "cached": false
  }
}

202 Accepted

{
  "status": "pending",
  "code": "CACHE_MISS_REFRESH_QUEUED",
  "message": "Try again in a moment",
  "domain": "example.com",
  "retry_after": 30,
  "credits_charged": 0,
  "billing_status": "not_charged",
  "request_id": "m8abc12-x9y8"
}

POST /v1/subdomains/bulk

Body Parameters

Parameter	Type	required
domains	string[]	required
verify	boolean Default `false`	optional
include_wildcards	boolean Default `false`	optional
limit	integer Default `500`	optional

Response Fields

Field	Type
`results[]`	unknown[]
`meta`	object
`meta.total`	integer
`meta.succeeded`	integer
`meta.failed`	integer
`meta.max_items`	integer
`meta.credits_per_item`	integer
`meta.duration_ms`	integer

Example Request

curl -X POST "https://domscan.net/v1/subdomains/bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "domains": [
    "example.com",
    "cloudflare.com"
  ],
  "verify": false,
  "limit": 500
}'

Example Response

{
  "results": [
    {
      "input": "example",
      "data": {}
    }
  ],
  "meta": {
    "total": 1,
    "succeeded": 1,
    "failed": 1,
    "max_items": 10,
    "credits_per_item": 1,
    "duration_ms": 1
  }
}