> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withgiga.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Subdomains

> Run standalone subdomain enumeration without a full audit

# Subdomains

The subdomains endpoint runs WithGiga's seven-source passive OSINT enumeration as a standalone operation — useful for surface discovery before scoping an engagement, or for keeping a continuously-updated inventory.

See [Subdomain Enumeration](/how-it-works/subdomain-enumeration) for the methodology.

***

## Start a subdomain scan

`POST /api/subdomains`

**Body**

```json theme={null}
{
  "domain": "acme.example.com"
}
```

| Field    | Type   | Description                         |
| -------- | ------ | ----------------------------------- |
| `domain` | string | Apex or subdomain to enumerate from |

**Response (201)**

```json theme={null}
{
  "success": true,
  "data": {
    "runId": "sub_abc123",
    "domain": "acme.example.com",
    "status": "running",
    "createdAt": "2026-05-18T12:00:00.000Z"
  }
}
```

The scan runs asynchronously. Poll the `runId` endpoint for results.

***

## Get scan results

`GET /api/subdomains/{runId}`

**Response (200)**

```json theme={null}
{
  "success": true,
  "data": {
    "runId": "sub_abc123",
    "domain": "acme.example.com",
    "status": "completed",
    "subdomains": [
      {
        "hostname": "app.acme.example.com",
        "sources": ["crtsh", "urlscan", "wayback"],
        "alive": true,
        "ports": [80, 443],
        "stack": ["nginx/1.24.0", "cloudflare"]
      },
      {
        "hostname": "admin.acme.example.com",
        "sources": ["crtsh"],
        "alive": true,
        "ports": [443],
        "stack": ["nginx/1.24.0"]
      },
      {
        "hostname": "old-staging.acme.example.com",
        "sources": ["wayback"],
        "alive": false
      }
    ],
    "summary": {
      "total": 47,
      "alive": 18,
      "uniqueSources": 7
    },
    "createdAt": "2026-05-18T12:00:00.000Z",
    "completedAt": "2026-05-18T12:01:42.000Z"
  }
}
```

| Status      | Description                             |
| ----------- | --------------------------------------- |
| `running`   | Sources are being queried               |
| `completed` | All sources returned, results validated |
| `failed`    | Unrecoverable error during enumeration  |

## Notes

* Enumeration is **passive only** — no traffic is sent to the target's infrastructure during source queries
* Validation (alive check, port scan, stack fingerprint) does generate traffic to the target
* Results are cached briefly; calling again for the same domain within 60 seconds may return the same scan