Lists the measurements of one keyword on an engine, country and device, newest first, paginated by cursor (limit up to 365): organic position (null = the domain was not in the top 30), absolute position, ranking URL and title, SERP features present, total results and when it was measured; source says whether it was measured by a check or imported. Without engine, country_code and device, the project's first engine, country and device are used. It also reads a combination the project no longer measures (retired_combos in seo_rankings.projects.get): that is its saved history, not today's positions. A position past 30 (an imported one) shows as null. The history is kept forever.
Alcance
seo_rankings:read
Permiso
Ver el módulo
Tool del MCP
seo_rankings_history_getEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.history.get".
Costo declarado: hasta 368 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).
Parámetros
keyword_idstringrutarequerido
Keyword id (from seo_rankings.keywords.list).
engineenumqueryopcional
Default: the first engine of the keyword's project.
Valores: google, bing
country_codestringqueryopcional
Default: the country of the project's first engine.
deviceenumqueryopcional
Default: the project's first device.
Valores: desktop, mobile
limitintegerqueryopcional
How many measurements, newest first (default 90, up to 365).
Por defecto: 90
cursorstringqueryopcional
The next_cursor of the previous page, exactly as it came (same keyword and filters); without it, the newest measurements.
Returns the keywords × dates grid of a project on one engine, country and device (default: the project's first ones; a combination the project no longer measures, listed in retired_combos of seo_rankings.projects.get, can be read too: its saved history, not today's positions). dates lists the check dates (ms, the UTC day at 00:00; newest first): the newest date_limit ones (up to 365; by default the dates that fit in about 250 cells, keywords × dates: 10 with up to 25 keywords, 2 with 100), or, with from, every date from the UTC day of from on (date_limit still caps them, 365 by default, keeping the newest: when the cap cuts, the dates closest to from are the ones left out, without truncated, so ask again with to before the oldest date returned); to (epoch ms, inclusive) ends the window at the UTC day of to, so an older stretch can be read on its own. grid maps each keyword id to its cell per date: position (null = not in the top 30), delta against the previous date shown (null on the oldest one), the ranking URL when there was one, checked_at (the exact time of that measurement, in ms: the newest of that UTC day) and check_id (its id, as in seo_rankings.history.get). Measurements of different engines or countries are separate grids, and the ones of the same collection pass share the same checked_at: check_id is a stable tie-breaker. All keywords of the project are included, active and inactive; a keyword without a cell on a date was not measured that day, and keywords maps each keyword id of grid to its text, so the grid reads on its own. A position past 30 (an imported one) shows as null, like every position outside the top 30. Keyword ids and dates are data keys and are returned as they are. Cost: one read per measurement of the dates returned, plus a short look-ahead without from; one call reads at most 12000 measurements (the declared cost): past that, truncated is true and the oldest dates are left out (every date returned is complete), so ask again with to before the oldest date returned. 400 invalid_range when from is after to; 404 rank_project_not_found. Requires view access to Rankings.
Alcance
seo_rankings:read
Permiso
Ver el módulo
Tool del MCP
seo_rankings_history_gridEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.history.grid".
Costo declarado: hasta 12000 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).
Parámetros
project_idstringrutarequerido
Rank project id (from seo_rankings.projects.list).
engineenumqueryopcional
Default: the project's first engine.
Valores: google, bing
country_codestringqueryopcional
Default: the country of the project's first engine.
deviceenumqueryopcional
Default: the project's first device.
Valores: desktop, mobile
date_limitintegerqueryopcional
How many check dates (columns), newest first, up to 365. Default: the dates that fit in about 250 cells (keywords × dates: 10 with up to 25 keywords, 2 with 100), at least one; with from, every date since from (365 at most).
fromintegerqueryopcional
Only check dates on or after the UTC day of this moment (epoch ms, inclusive).
tointegerqueryopcional
Only check dates on or before the UTC day of this moment (epoch ms, inclusive).
include_keywordsbooleanqueryopcional
true (default) adds keywords, the text of each keyword of the grid (one read per keyword, inside the declared cost); false skips it when you already have them from seo_rankings.keywords.list.
Respuesta
project_idstring
enginestring
country_codestring
devicestring
datesarray<number>
Check dates (ms, the UTC day), newest first: the columns of the grid.
gridobject
keyword id → { date (ms, as in dates) → cell }. A missing cell = not measured that day; position null = measured, not in the top 30.
keywordsobject
keyword id → keyword text, for every keyword in grid (so the grid reads on its own).
truncatedboolean
true = the read ceiling cut the grid: the oldest dates of the window are missing (every date given is complete); ask for them with to.
