Get a release report
Clicks, impressions, CTR and position for the weeks before and after a logged release, read live from Google, Bing or Yandex.
https://api.rankparse.com/v1/releases/reportFreeAPI keyCompares the days before a release with the same number of days after it, for one search engine. The release day itself is left out of both sides, and days is a whole number of weeks (7, 14 or 28) so both sides hold the same weekdays.
Search engines report only days that had impressions, and their latest figures trail by about two days. A day with no row, for which final data already exists and that falls after the engine's first reported day, counts as zero. A day after that cutoff is not known yet, and a day before the engine's first reported day is not known either (the website may have been added to it part way through the window), so neither is counted as a zero. Both sides always cover the same number of days: while the after side is still filling, the before side is cut to the same number of days nearest the release; once a week is in, both are cut to a whole number of weeks. days and days_observed in before and after say how many days were compared, and the daily series still lists every observed day. A young release answers too_early until seven days after it have final data.
The verdict is only increase or decrease when the change in average daily clicks is at least 5% and more than two standard errors, measured on the daily swings in the two windows. Treat the result as a correlation. Weeks around a release also hold seasonality, algorithm updates and other releases, which is why other_releases_in_window lists the other changes you logged in the same weeks.
Query parameters
release_idstringrequiredThe release, from List releases. An unknown ID returns 404 release_not_found.
enginestringdefault googlegoogle, bing or yandex. Bing and Yandex report the whole site per day. A release logged with page_contains can only be read with google (400 unsupported_filter otherwise).
daysintegerdefault 14Days on each side of the release: 7, 14 or 28. Anything else returns 400 invalid_window.
breakdownstringgoogle only. page or query adds movers: the ten biggest gaining and losing pages or queries, over the days that have data on both sides.
sitestringThe property to read, such as sc-domain:reepl.io. It defaults to the release's host, and a bare host is matched to the property you own.
Response
releaseobjectThe release being reported on.
sourcestringgoogle, bing or yandex, with site the property used (and requested_site when it differs from what was asked).
beforeobjectThe window before the release: start_date, end_date, days, days_observed, clicks, impressions, ctr, position (weighted by impressions, null when nothing was shown), avg_daily_clicks and avg_daily_impressions.
afterobjectThe window after the release, with the same fields. While the window is still filling, days and days_observed are the number of days after the release that have final data, and the before window holds the same number of days.
changeobjectAfter minus before, per observed day: avg_daily_clicks, avg_daily_clicks_pct, avg_daily_impressions, avg_daily_impressions_pct and ctr. position is before minus after, so a positive number means the pages moved up. Percentages are null when the before window had none.
verdictstringincrease, decrease, no_clear_change, too_early (fewer than seven days after the release have final data) or no_baseline (fewer than seven days with data, or no clicks, before it).
summarystringOne sentence stating the result with the caveat that applies.
dailyarrayOne row per day with data available: date, window (before, release_day or after), clicks, impressions and position.
moversobjectWith breakdown: dimension, window_days and the gainers and losers arrays, each entry with keys, clicks, previous_clicks, clicks_delta, impressions_delta, position_delta and status (both, new or lost).
other_releases_in_windowarrayOther releases of the same host dated inside the compared weeks.
Behavior and limits
- Credits: 0. It reads the provider live on every call. Bing and Yandex count against the workspace's daily limit of 300 live reads per engine.
- Needs a connection: the engine must be connected in Settings, Connections. A missing connection returns the same
400 ..._not_connectederror as the Search Console, Bing and Yandex endpoints. - Breakdown size: the page and query breakdown reads Google's top 1000 rows per window, and a
notesays when that was reached.
Errors
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_release | release_id is missing. |
| 400 | invalid_engine, invalid_window, invalid_breakdown | A parameter is out of range. |
| 400 | unsupported_breakdown | breakdown was used with Bing or Yandex. |
| 400 | unsupported_filter | The release has page_contains and the engine is not google. |
| 400 | release_in_future | The release is dated after today. |
| 400, 401, 404, 503 | provider codes | The engine is not connected, the connection needs reconnecting, the property was not found, or the provider failed. They are the same codes as the Search Console, Bing and Yandex endpoints. |
| 401 | invalid_api_key | Missing, invalid or revoked API key. |
| 404 | release_not_found | No release with that ID in your workspace. |
| 429 | rate_limited | More than 60 requests per minute for this key. |
Related
MCP tool: get_release_report (accepts release_id, days, engine, breakdown, site).