Volume de busca · Rankings · Referência da API

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

Refresh search volume data

seo_rankings.volume.fetch

EscritaDesde 2026-11-01

Fetches from DataForSEO (paid; one call per 700 keywords) the monthly search volume, CPC, competition and 12-month trend of the project's ACTIVE keywords (or of the keyword_ids given, active ones only) and stores them on each keyword, using the location and language of the project's first engine. Returns how many keywords were requested and updated, how many failed on the provider side, and the calls made. Use it after adding keywords without search volume or to refresh stale data; it does not measure positions. Not available in demo organizations: 403 demo_read_only, already on the dry run. Outside the app it needs a dry run and its confirm_token (it pays DataForSEO).

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_volume_fetchNa superfície completa; na compacta, mb_execute_operation com id: "seo_rankings.volume.fetch".

Custo declarado: até 502 leituras e 500 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).

keyword_idsarray<string>corpoopcional

Only these keywords. Default: every ACTIVE keyword of the project.

Resposta

updatednumber

requestednumber

failednumber

callsnumber

skipped_inactivenumber

not_foundarray<string>

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}/volume" \
  -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.