---
title: "Start an on-demand check of a project's keywords"
method: POST
path: "/projects/{project_id}/checks"
tags: ["Checks"]
---

# Start an on-demand check of a project's keywords

`POST /projects/{project_id}/checks`

## Request

- Base URL: `https://adslighthouse.com/api/v1`
- URL: `https://adslighthouse.com/api/v1/projects/{project_id}/checks`
- Auth: HTTP bearer

Queues an on-demand check of the project's active keywords, or one keyword, across its locations, devices and search engines, using the on-demand allowance (one check per keyword × location × device × source). The searches run in the background; poll get_check_status. Requires the write scope and an idempotency key: a retry with the same key never reserves or runs the checks again. Confirm with the user before calling.

## Path parameters

- `project_id` string, required: The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.

## Headers

- `Idempotency-Key` string, required: A unique value you choose for this request, such as a UUID. Repeating the same key returns the first result instead of starting paid work again.

## Request body

- object
  - `keyword_id` string: Check only this keyword.
  - `device` 'desktop' | 'mobile': Check only this device.
  - `os` 'windows' | 'macos' | 'android' | 'ios': Pin an operating system that fits the device.

## Response `202`

Start an on-demand check of a project's keywords

- object
  - `run_id` string, required
  - `project_id` string, required
  - `reused` boolean, required: True when this answer repeats an earlier request with the same key, or joins an identical check that is still running. No checks were reserved again.
  - `total` integer, required: Searches in the run: keyword × location × device × source.
  - `completed` integer, required
  - `failed` integer, required
  - `pending` integer, required
  - `expired` boolean, required: True when some of the run's job records were already cleaned up.
  - `request_id` string

## Other responses

- `400`: Invalid parameters, cursor or body.
- `401`: Missing, invalid, expired or revoked credential.
- `403`: The credential lacks the write scope, the plan does not include the API, or the allowance is used up.
- `404`: Unknown project, keyword or run in this account.
- `409`: The idempotency key was already used for a different request.
- `429`: Rate limit reached. Retry after the Retry-After seconds.
- `503`: The requested service or file is temporarily unavailable.

---

[API](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api.md) · [All operations](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api/revisions/e1a4a40b11a9?raw)