# Search & extraction

Search results, page extraction, and SERP analysis.

All paths below are relative to `https://www.agentseo.dev/api/v1`. Send your key in `x-api-key`. Set `AGENTSEO_API_KEY` in your environment before running the examples. IDs and results are illustrative.

[Async result handling](https://www.agentseo.dev/docs/async-jobs) · [Errors and limits](https://www.agentseo.dev/docs/errors) · [OpenAPI contract](https://www.agentseo.dev/openapi.yaml)

## POST`/search`

Perform a Google search with optional domain filtering. Returns raw SERP evidence plus agent\_support so an agent can choose the next workflow.

Request fields · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `query`Required | string | Search query |
| `location` | string | Target location (default: United States) |
| `location_code` | integer | Optional search location code for deterministic geo-targeting |
| `language` | string | ISO code (default: en) |
| `limit` | integer | Max results (1-50, default: 10) |
| `include_domains` | array | Only return results from these domains |
| `exclude_domains` | array | Exclude results from these domains |

POST /search example

```
curl -X POST https://www.agentseo.dev/api/v1/search?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"best crm software", "location":"Austin, TX", "location_code":1026201, "limit":5}'
```

## POST`/extract`

Extract clean content (markdown/text/html) from any URL. Returns page metadata, structural headings, and agent\_support for follow-up workflow selection.

Request fields · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `url`Required | string | Target URL |
| `format` | enum | markdown, text, html (default: markdown) |
| `include_images` | boolean | Include image extraction (default: false) |

POST /extract example

```
curl -X POST https://www.agentseo.dev/api/v1/extract \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tcrn.ch/example"}'
```

## POST`/analyze/serp`

Analyze SERP features (Local Pack, AI Overview, Shopping) for a keyword. Returns serp\_opportunity so agents can infer intent, competition, and the right content format.

Request fields · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `keyword`Required | string | Target keyword |
| `location` | string | Target location (default: US) |
| `location_code` | integer | Optional search location code for deterministic geo-targeting |
| `device` | enum | desktop or mobile (default: desktop) |
| `language` | string | ISO code (default: en) |

POST /analyze/serp example

```
curl -X POST https://www.agentseo.dev/api/v1/analyze/serp?sync=true \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"plumbers near me", "location":"Austin, TX", "location_code":1026201, "device":"mobile"}'
```

[← All endpoints](https://www.agentseo.dev/docs/api-reference)

---
Canonical HTML: https://www.agentseo.dev/docs/api-reference/search
Markdown: https://www.agentseo.dev/docs/api-reference/search/index.md