Lists the organization's rank tracking projects, oldest first, paginated by cursor (limit up to 200). An account normally has one project (the domain it tracks); each row brings the domain, the engines and countries measured, devices, the check schedule, active/inactive keyword counts, the status and date of the last check, the next scheduled check, the manual checks used and left this month, the plan's ranking quota, and the position summary of the last check (check_summary: the position bands top3 = 1–3, top10 = 4–10, top20 = 11–20, top30 = 21–30 and not_ranked, the average position of the keywords in the top 30, and the top gainers and losers on the main engine, country and device: among the ones measured today, the one with the most active keywords with a position, ties going to the project's order). Each project also brings measured_pos_keys (the engine, country and device combinations it measures today, as {engine}_{country}_{device}), combo_summaries (one pair per combination measured today that already has measurements: current_summary and previous_summary, the check before of that SAME combination or null; primary marks the one in check_summary) and retired_combos (the combinations it no longer measures: their history stays readable with seo_rankings.history.grid, never as today's positions). Use seo_rankings.keywords.list for the keywords and their positions.
Escopo
seo_rankings:read
Permissão
Ver o módulo
Tool do MCP
seo_rankings_projects_listNa superfície completa; na compacta, mb_execute_operation com id: "seo_rankings.projects.list".
Custo declarado: até 202 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
limitintegerqueryopcional
How many items this page brings at most (see the maximum and the default in the schema).
Padrão: 50
cursorstringqueryopcional
The next_cursor of the previous page, exactly as it came (only for the same list and filters); without it, the first page.
Returns one rank tracking project: domain, engines and countries (with the engine keys used elsewhere, {engine}_{country}), devices, schedule, keyword counts, last and next check, manual checks used and remaining this month (UTC), the ranking quota of the plan and the position summary of the last check on the main engine, country and device (check_summary: among the combinations measured today, the one with the most active keywords with a position, ties going to the project's order; previous_summary is the check before of the SAME combination, or null when there is none, never another country's or device's), including the keywords that rose or dropped the most since the previous check (gainers and losers, up to 5 each: the quickest answer to «which keywords went down»). combo_summaries brings the same pair for every combination measured today that already has measurements (primary marks the main one; one in measured_pos_keys without an entry has none yet: they arrive with the next check), measured_pos_keys lists the combinations measured today and retired_combos the ones the project no longer measures (with their first and last measurement; their history stays in seo_rankings.history.grid). Every summary brings last_checked_at, its newest measurement; compare positions only within the same engine, country and device. Its distribution is in BANDS, not cumulative: top3 = positions 1–3, top10 = 4–10, top20 = 11–20, top30 = 21–30, not_ranked = no position in the top 30 (so «in the first page» is top3 + top10); average_position averages only the keywords in the top 30. last_check_status is dispatching, pending, collecting, completed or failed while a check runs or after it ends. Not found if the id is not a project of this organization.
Escopo
seo_rankings:read
Permissão
Ver o módulo
Tool do MCP
seo_rankings_projects_getNa superfície completa; na compacta, mb_execute_operation com id: "seo_rankings.projects.get".
Custo declarado: até 1 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
project_idstringrotaobrigatório
Rank project id (from seo_rankings.projects.list).
Resposta
idstring
namestring
domainstring
Host measured (example.com; subdomains count).
enginesarray<object>
Engine and country combinations measured.
devicesarray<string>
Devices measured: desktop and/or mobile.
scheduleobject
When the scheduled check runs.
keyword_countnumber
Active keywords (they count against the quota).
inactive_keyword_countnumber
Paused keywords (history kept).
last_check_atnumber | null
last_check_statusstring | null
Status of the latest check batch: dispatching, pending, collecting, completed or failed.
next_check_atnumber | null
Next scheduled check (ms); null when the schedule is off.
manual_checks_usednumber
Manual checks used this month (UTC).
manual_checks_remainingnumber
quotaobject
The plan's ranking quota.
check_summaryobject | null
Summary of the main engine, country and device (its pos_key) after the latest check; null when nothing the project measures today has been measured yet.
previous_summaryobject | null
The check before, of the SAME engine, country and device as check_summary (same pos_key); null when there is none, never another combination's.
measured_pos_keysarray<string>
The engine, country and device combinations the project measures today, {engine}_{country}_{device}, in the project's order (engines, then devices): only these are today's positions.
combo_summariesarray<object>
One pair of summaries per combination measured today that already has measurements, in the project's order: its latest check (current_summary) and the check before of that SAME combination (previous_summary); primary marks the one in check_summary. Positions are compared only within one combination.
retired_combosarray<object>
Combinations the project measured and no longer measures, the most recently measured first. Their history stays readable with seo_rankings.history.grid (with that engine, country and device): it is never a position of today.
Creates the rank tracking project of the organization: the domain to track (a host like example.com; protocol, path and port are dropped, positions match the host and its subdomains), the engine and country combinations to measure (google or bing + ISO country; supported countries fill in location and language, others need location_name and language_code), the devices (default desktop) and the check schedule (default weekly, Monday 09:00 UTC, enabled, as in the app: once the project has keywords a check runs by itself every week, DataForSEO included in the plan; send schedule.enabled false to create it paused, and next_check_at in the answer says when the first one runs). An account has ONE project (409 rank_project_exists if it already has one: edit it instead). The engines and devices are capped by the plan's ranking quota (409 limit_reached, details.resource rank_engines / rank_devices). Keywords are added afterwards with seo_rankings.keywords.add. Nothing is measured until a scheduled or manual check runs.
Escopo
seo_rankings:write
Permissão
Editar no módulo
Tool do MCP
seo_rankings_projects_createNa superfície completa; na compacta, mb_execute_operation com id: "seo_rankings.projects.create".
Custo declarado: até 2 leituras e 1 escritas por chamada (contam na cota diária).
Parâmetros
domainstringcorpoobrigatório
Domain to track (example.com). A protocol, path or port is dropped: positions are matched by host, subdomains included.
enginesarray<object>corpoobrigatório
Engine and country combinations to measure (each one is paid per keyword and device on every check). Limited by the plan's ranking quota (quota.max_engines of the project).
namestringcorpoopcional
Display name. Default: the domain.
devicesarray<enum>corpoopcional
Devices to measure. Default: [desktop]. Limited by the plan's ranking quota (quota.max_devices of the project).
Updates the domain, name, engines and countries, devices or schedule of a project; only the fields sent change. Send the whole list: engines and devices replace it; use dry_run to see what a change stops measuring (its items are those combinations, by pos_key, and counts.positions_cleared the latest positions it would clear; it writes nothing, and running the change does not need its confirm_token). Adding a country to a project with 2+ engines keeps the existing keywords measuring where they were (keywords_stamped says how many; opt them in with seo_rankings.keywords.bulk.set_engines); removing a country that some ACTIVE keyword is measured on only there is refused (409 rank_engine_in_use: assign them another country or deactivate them first). What the project already has is kept even above the plan's quota; only growing past it is refused. A new schedule recomputes the next scheduled check. Removing or changing a country or a device clears the latest positions measured there (the history stays: it is listed in retired_combos and readable with seo_rankings.history.grid) and recomputes the summaries; a combination that comes back starts without a previous position. Returns the updated project, keywords_stamped, positions_cleared (the latest positions removed) and retired_pos_keys (the combinations it stopped measuring that had positions: the ones noted in retired_combos).
Escopo
seo_rankings:write
Permissão
Editar no módulo
Tool do MCP
seo_rankings_projects_updateNa superfície completa; na compacta, mb_execute_operation com id: "seo_rankings.projects.update".
Deletes a rank tracking project with ALL its keywords, their whole position history and its check batches. The trash keeps a read-only copy of the project and its keywords for 30 days; it cannot be restored from there (the history is gone and an account has one project), so this is for good. To stop paying for checks without losing anything, disable the schedule with seo_rankings.projects.update instead; to stop measuring some keywords, deactivate them. Outside the app it always needs a dry run (which counts the keywords and measurements) and a confirm_token; the REST DELETE does not confirm it in line.
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:writee «Permitir exclusões» (seo_rankings:delete no OAuth)
Permissão
Editar no módulo
Tool do MCP
seo_rankings_projects_deleteNa superfície completa; na compacta, mb_execute_operation com id: "seo_rankings.projects.delete".
