Checks

Run a manual rank check

seo_rankings.checks.trigger

Starts a manual rank check of a project now: every ACTIVE keyword is sent to the SERP provider (DataForSEO, paid per keyword, engine and country, and device) and the positions are collected over the following minutes. The plan allows a limited number of manual checks per project per month (UTC; 409 limit_reached with resource rank_manual_checks when used up; scheduled checks are not affected), a check already in progress blocks a new one (409 rank_check_in_progress), and a project without active keywords has nothing to check (409 rank_no_active_keywords). Returns the batches and SERP tasks dispatched and the manual checks left this month. Results are NOT in the response: watch last_check_status in seo_rankings.projects.get (pending → collecting → completed) or subscribe to seo_rankings.check.completed; positions are then in seo_rankings.keywords.list. Not idempotent: each call is a new paid check. In demo organizations nothing is measured live: 403 demo_read_only, already on the dry run (no manual check of the month is used). Outside the app it needs a dry run and its confirm_token (it pays DataForSEO).

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

seo_rankings:write

Permission

Edit in the module

MCP tool

seo_rankings_checks_triggerOn the full surface; on the compact one, mb_execute_operation with id: "seo_rankings.checks.trigger".

Events it can emit

seo_rankings.check.completedseo_rankings.check.failed

Declared cost: up to 302 reads and 50 writes per call (they count against the daily quota). Touches an external platform (dataforseo): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/seo/rankings/projects/{project_id}/check" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.