Checks

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

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.

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

Path parameters

project_idstring 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-Keystring 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

keyword_idstring

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

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

run_idstring required
project_idstring required
reusedboolean 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.

totalinteger required

Searches in the run: keyword × location × device × source.

completedinteger required
failedinteger required
pendinginteger required
expiredboolean required

True when some of the run's job records were already cleaned up.

request_idstring

Changes

No recorded changes to this operation across all 1 revision of this API.