---
title: "Start a subdomain search"
method: POST
path: "/find-subdomains/searches/"
tags: ["find-subdomains"]
---

# Start a subdomain search

`POST /find-subdomains/searches/`

## Request

- Base URL: `https://api.getoneprofile.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getoneprofile.ai/find-subdomains/searches/`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Begin reading the public record of subdomains for a domain. Returns immediately with a pending search; poll the search endpoint until it reaches a terminal status. It usually answers in seconds, but a domain the fast index does not cover falls back to reading raw certificate logs, which is slow and frequently has to be retried. That is why this does not answer inline.

## Request body

- StartSubdomainSearchRequestSchema: Start a search for one domain's subdomains.
  - `domain` string, required: The domain to search, e.g. slack.com. A pasted URL is trimmed.

## Response `201`

Successful Response

- SubdomainSearchResponseSchema: One search and whatever it has found so far.
  - `created_at` string, date-time, required
  - `domain` string, required
  - `error` string, nullable, required
  - `error_code` string, nullable, required
  - `hostnames` string[], required: Discovered hostnames, newest first sighting first. Empty until the search succeeds. At most the per-search cap (5,000 by default): a larger domain is trimmed to its newest names and partial is true.
  - `hostnames_found` integer, required: How many distinct hostnames the search found, before the per-search cap. Larger than len(hostnames) when the cap trimmed the list; use this for the headline count.
  - `id` string, uuid, required
  - `partial` boolean, required: True when hostnames is a slice of what was found, which is when hostnames_found exceeds len(hostnames). The names kept are the newest first sightings.
  - `retryable` boolean, required: Whether running the same search again could plausibly work.
  - `rows_created` integer, required
  - `rows_to_add` integer, required: How many rows turning this search into a table would add: the hostnames stored, cut to the plan's rows per table. Put it on the create button; 0 until the search succeeds.
  - `status` 'pending' | 'running' | 'succeeded' | 'failed', required: Where one subdomain search has got to.
  - `table_id` string, uuid, nullable, required

## Other responses

- `401`: Unauthorized
- `402`: Not enough credits, or the plan does not include subdomain search.
- `403`: Forbidden
- `422`: Invalid request made to the API.
- `500`: Internal server error.
- `502`: Bad gateway error.
- `503`: Service unavailable.

---

[API](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile.md) · [All operations](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile/llms.txt) · [OpenAPI document](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile/revisions/4a6bd71e3f02?raw)