# Subdomain Finder API

URL: https://www.deepinfo.com/data-api/apis/subdomain-finder/

## List Every Subdomain the Index Knows Under a Domain.

The Subdomain Finder API takes a registered domain and returns the subdomains Deepinfo’s index holds under it, each one a full domain record rather than a bare hostname, so its A records, certificate and web data arrive with it.

[Talk to us about access](https://www.deepinfo.com/contact/?topic=data-api) [Subdomain Finder reference](https://docs.deepinfo.com/reference/discovery/subdomain-finder/)

### Hostnames That Arrive With Their Records.

Each subdomain record carries its parent’s WHOIS next to its own DNS, so ownership and resolution come back in one object.

GET `https://api.deepinfo.com/v1/discovery/subdomain-finder` [Reference](https://docs.deepinfo.com/reference/discovery/subdomain-finder/)

| Parameter | Type |  | Description |
| --- | --- | --- | --- |
| `domain` | string | Required | A registered domain, for example `deepinfo.com`. |
| `page` | integer | Optional | Page number, from 1. |
| `page_size` | integer | Optional | Results per page. |
| `ordering` | string | Optional | Field to sort by. Prefix `-` for descending. |
| `export` | boolean | Optional | Return the result as an export instead of a page. Default `false`. |
| `export_format` | string | Optional | `json` or `csv`. |
| `export_scope` | string | Optional | How much of each record to include: `basic`, `default` or `extended`. |

Request

curl:

```bash
curl "https://api.deepinfo.com/v1/discovery/subdomain-finder?domain=acme.example&page_size=25" \
  -H "apikey: YOUR_API_KEY"
```

Python:

```python
import requests

r = requests.get(
    "https://api.deepinfo.com/v1/discovery/subdomain-finder",
    params={"domain": "acme.example", "page_size": 25},
    headers={"apikey": "YOUR_API_KEY"},
)
data = r.json()
print(data["result_count"])
for d in data["results"]:
    a = (d.get("dns") or {}).get("a") or {}
    print(d["punycode"], a.get("ip_addresses"))
```

JavaScript:

```javascript
const r = await fetch(
  'https://api.deepinfo.com/v1/discovery/subdomain-finder?domain=acme.example&page_size=25',
  { headers: { apikey: 'YOUR_API_KEY' } }
)
const { result_count, results } = await r.json()
console.log(result_count, results.map((d) => d.punycode))
```

Response

200 OK · application/json

```json
{
  "page": 1,
  "page_size": 25,
  "result_count": 3,
  "results": [
    {
      "punycode": "vpn.acme.example",
      "unicode": "vpn.acme.example",
      "is_idn": false,
      "subdomain_level_count": 1,
      "domain": {
        "punycode": "acme.example",
        "whois": {
          "registrar": "…",
          "expiry_date": "2027-03-14T00:00:00Z"
        }
      },
      "dns": {
        "a": { "ip_addresses": ["203.0.113.24"] }
      },
      "ssl": {
        "validity": { "end_date": "2026-12-01T23:59:59Z" }
      }
    },
    {
      "punycode": "staging.acme.example",
      "unicode": "staging.acme.example",
      "is_idn": false,
      "subdomain_level_count": 1,
      "dns": {
        "a": { "ip_addresses": ["198.51.100.7"] }
      }
    },
    {
      "punycode": "mail.eu.acme.example",
      "unicode": "mail.eu.acme.example",
      "is_idn": false,
      "subdomain_level_count": 2,
      "dns": {
        "a": { "ip_addresses": ["203.0.113.60"] }
      }
    }
  ]
}
```

### Export the Whole List as One File.

Set `export=true` to get the result as JSON or CSV instead of a page. `export_scope` decides how much of each record comes with it: `basic`, `default` or `extended`.

In CSV, nested fields flatten into dotted column names. The parent domain’s WHOIS dates and registrar sit on each hostname’s row.

[Export parameters in the reference](https://docs.deepinfo.com/reference/discovery/subdomain-finder/#ref-query-parameters)

Request:

```bash
curl "https://api.deepinfo.com/v1/discovery/subdomain-finder?domain=deepinfo.com&export=true&export_format=csv&export_scope=basic" \
  -H "apikey: YOUR_API_KEY"
```

CSV header:

```
page,page_size,result_count,results.punycode,results.unicode,results.domain.whois.create_date,results.domain.whois.update_date,results.domain.whois.expiry_date,results.domain.whois.registrar,…
```

### Hostname Lists Feed These Workflows.

#### [Attack Surface Management](https://www.deepinfo.com/solutions/use-cases/attack-surface-management/)

List the hostnames under each of your domains and compare them with what your CMDB says you run.

#### [Third-Party Risk](https://www.deepinfo.com/solutions/use-cases/third-party-risk-management/)

See what a supplier exposes under its own domain before you connect it to yours.

#### [M&A Due Diligence](https://www.deepinfo.com/solutions/use-cases/mergers-acquisitions-due-diligence/)

Map a target’s hostnames from the outside, instead of relying on the list in the data room.

#### [Subsidiary Oversight](https://www.deepinfo.com/solutions/use-cases/subsidiary-oversight/)

Run the call across each group company’s domain and keep one list of what the group has online.

### Keep the List Current.

- [Daily Discovered Subdomains](https://www.deepinfo.com/data-api/feeds/daily-discovered-subdomains/) (Feed): The subdomains added to the index each day, as one file.
- [Domain Detail](https://www.deepinfo.com/data-api/apis/domain-detail/) (Discovery): The full record for one name, in the shape this call returns.
- [All TLDs](https://www.deepinfo.com/data-api/apis/all-tlds/) (Discovery): Registrations of one name under other extensions.

### See This Data at Work in the Deepinfo Platform

External Attack Surface Management runs these lookups continuously over your assets and raises what changes as issues, and Deep Search & Insights opens the whole index to your analysts.

- [External Attack Surface Management](https://www.deepinfo.com/platform/easm/) (EASM)
- [Deep Search & Insights](https://www.deepinfo.com/platform/dsi/) (DSI)
- [How the Platform Works](https://www.deepinfo.com/platform/how-it-works/)

### Questions About Subdomain Finder API

**Where do the subdomains come from?**

From Deepinfo’s own index, which also runs discovery in the platform. The response does not attribute a source or a first-seen date to each hostname.

**Can we query a domain we don’t own?**

Yes. The call reads Deepinfo’s index, so it works for any registered domain: a supplier, an acquisition target or a domain under investigation.

**Does the list show which subdomains are live?**

Each record carries its DNS records and the outcome of Deepinfo’s last web visit in `webdata.connection_status`, as the index last observed them. To check one host as it is now, call [DNS](https://www.deepinfo.com/data-api/apis/dns-lookup/) or [Web Data](https://www.deepinfo.com/data-api/apis/webdata-lookup/).

**How do we track new subdomains over time?**

Diff successive calls, or take the [Daily Discovered Subdomains feed](https://www.deepinfo.com/data-api/feeds/daily-discovered-subdomains/). For your domains, [Asset Discovery](https://www.deepinfo.com/platform/easm/smart-asset-discovery/) in EASM does this continuously and asks your team to approve what it finds.

**Can we see which subdomains changed most recently?**

Sort with `ordering`. `ordering=-ssl_last_change_date` puts the most recent certificate change first, and each record also carries `dns_last_change_date` for DNS changes.

**How is the Subdomain Finder API priced?**

As part of an API services plan, priced by volume and frequency, separately from the platform. See [Data & API pricing](https://www.deepinfo.com/pricing/#data-pricing).

### See What Sits Under Your Domain.

Run the finder against your own domains with our team on a short call.

[Talk to us about access](https://www.deepinfo.com/contact/?topic=data-api) [All API services](https://www.deepinfo.com/data-api/apis/)