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

# Start a SERP rank-check job

`POST /v1/serp/rank-check`

## Request

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

Starts an asynchronous capture and projects requested domains' first-page
ranks at read time. Poll via `GET /v1/serp/rank-check/{jobId}`.

## Request body

- object
  - `query` string, required
  - `domains` string[], required: Domains or URLs to locate in the results
  - `engine` 'google' | 'bing'
  - `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)