Verificações · Rankings · Referência da API

POST/v1/seo/rankings/projects/{project_id}/check

Run a manual rank check

seo_rankings.checks.trigger

EscritaDesde 2026-11-01

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).

Instruções para agentes

Tell the person the check is running and that positions usually arrive within 15 to 60 minutes; do not call it again for the same project until it finished.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo: seo_rankings:write
Permissão: Editar no módulo
Tool do MCP: seo_rankings_checks_triggerNa superfície completa; na compacta, mb_execute_operation com id: "seo_rankings.checks.trigger".
Eventos que pode emitir: seo_rankings.check.completed seo_rankings.check.failed

Custo declarado: até 302 leituras e 50 escritas por chamada (contam na cota diária). Usa uma plataforma externa (dataforseo): conta na cota de operações externas.

Parâmetros

project_idstringrotaobrigatório

Rank project id (from seo_rankings.projects.list).

Resposta

batch_countnumber

tasks_dispatchednumber

keyword_countnumber

checks_remainingnumber

Erros

rank_project_not_found confirmation_required external_rejected external_unavailable external_rate_limited sandbox_external_unavailable invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.