---
title: "Start a SERP capture job"
method: POST
path: "/v1/serp/search"
tags: ["SERP"]
---

# Start a SERP capture job

`POST /v1/serp/search`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/serp/search`
- Auth: HTTP bearer

Starts an asynchronous search-results capture (202-plus-poll). Returns
a job id to poll via `GET /v1/serp/search/{jobId}`.

## Request body

- object
  - `query` string, required
  - `engine` 'google' | 'bing'
  - `num` integer
  - `gl` string
  - `hl` string

## Response `202`

Job accepted

- SerpJobAck
  - `id` string, required: Job id (format "serp-<uuid>"), used to poll the result
  - `query` string, required
  - `status` 'running' | 'completed' | 'failed', required

## Other responses

- `400`: Invalid request

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)