Projects

List rank tracking projects

seo_rankings.projects.list

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.

Scope

seo_rankings:read

Permission

View the module

MCP tool

seo_rankings_projects_listOn the full surface; on the compact one, mb_execute_operation with id: "seo_rankings.projects.list".

Declared cost: up to 202 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/seo/rankings/projects" \
  -H "Authorization: Bearer $MB_API_KEY"

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.

curl "https://api.mb-suite.com/v1/seo/rankings/projects" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get a rank tracking project

seo_rankings.projects.get

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.

Scope

seo_rankings:read

Permission

View the module

MCP tool

seo_rankings_projects_getOn the full surface; on the compact one, mb_execute_operation with id: "seo_rankings.projects.get".

Declared cost: up to 1 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/seo/rankings/projects/{project_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

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.

curl "https://api.mb-suite.com/v1/seo/rankings/projects/{project_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create the rank tracking project

seo_rankings.projects.create

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.

Scope

seo_rankings:write

Permission

Edit in the module

MCP tool

seo_rankings_projects_createOn the full surface; on the compact one, mb_execute_operation with id: "seo_rankings.projects.create".

Events it can emit

seo_rankings.project.created

Declared cost: up to 2 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/seo/rankings/projects" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "domain": "DOMAIN",
  "engines": []
}'

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.

curl -X POST "https://api.mb-suite.com/v1/seo/rankings/projects" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "domain": "DOMAIN",
  "engines": []
}'

Update a rank tracking project

seo_rankings.projects.update

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

Scope

seo_rankings:write

Permission

Edit in the module

MCP tool

seo_rankings_projects_updateOn the full surface; on the compact one, mb_execute_operation with id: "seo_rankings.projects.update".

Events it can emit

seo_rankings.project.updated

Declared cost: up to 302 reads and 302 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/seo/rankings/projects/{project_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

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.

curl -X PATCH "https://api.mb-suite.com/v1/seo/rankings/projects/{project_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete a rank tracking project

seo_rankings.projects.delete

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.

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 and “Allow deletions” (seo_rankings:delete in OAuth)

Permission

Edit in the module

MCP tool

seo_rankings_projects_deleteOn the full surface; on the compact one, mb_execute_operation with id: "seo_rankings.projects.delete".

Events it can emit

seo_rankings.project.deleted

Declared cost: up to 20000 reads and 20000 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/seo/rankings/projects/{project_id}" \
  -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.

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