Developers

API and MCP documentation

Read-only access to your Search Console data in SEO Signal. Last updated: 16 November 2026

Everything here is read-only. A key can look at your Search Console data in SEO Signal, but it cannot change a site, a project or a setting. The base address is https://app.seosignal.net.

Quick start

  1. Sign in to app.seosignal.net, open Account → Developer and create an API key. The key starts with ssk_ and is shown once; we store only a hash of it.
  2. Choose what it may read: the Search Console Assistant, the Rank Tracker, or both, and switch MCP on or off.
  3. Call the API:
curl https://app.seosignal.net/api/v1/sites \
  -H "Authorization: Bearer ssk_YOUR_KEY"

The API and MCP are included in every paid plan. The free trial does not include them: if you do not see Developer under Account, you are on the trial or have no active plan, and upgrading turns it on.

Authentication

WhereHow the key is sent
REST (/api/v1/…)Authorization: Bearer ssk_… or the header X-Api-Key: ssk_…. A key in the query string is not accepted on REST.
MCP (/api/mcp)The same headers, or ?token=ssk_… in the address, because most MCP clients are configured with a URL only.

A key belongs to one account and one plan. It stops working at once when you revoke or replace it, or when the account is locked. A replacement key keeps the access choices of the key it replaces.

Response format

Every response is JSON (Content-Type: application/json), field names are snake_case, ids are strings, and dates are YYYY-MM-DD. Successful responses use one envelope:

{
  "data": [ … ],
  "meta": {
    "report": "queries",
    "site": { "id": "1", "url": "https://example.com/" },
    "period": { "from": "2026-11-08", "to": "2026-11-14", "days": 7 },
    "data_through": "2026-11-14",
    "pagination": { "total": 120, "page": 2, "per_page": 50, "total_pages": 3 },
    "request_id": "req_4k2m9x0c1a7b3d5e8f6g"
  }
}

data is an array for lists and an object for single reports. meta always carries request_id; the other fields depend on the report.

Errors use another envelope, with a stable code to program against and a readable message:

{
  "error": {
    "code": "invalid_parameter",
    "message": "\"days\" must be between 1 and 240.",
    "status": 422,
    "request_id": "req_4k2m9x0c1a7b3d5e8f6g",
    "details": { "field": "days" }
  }
}

Response headers

The facts a client needs for paging and caching are also in X-* headers, so you can read them without parsing the body.

HeaderSent onMeaning
X-Request-Idevery responseId of this request. Send your own X-Request-Id (8 to 64 letters, digits, . _ -) and it is echoed back. Quote it when you contact support.
X-API-Versionevery responseAPI version, currently 1.
X-Daily-LimitauthenticatedRequests allowed per day for the account.
X-Daily-RemainingauthenticatedRequests left today. The count resets at midnight, server time.
X-ReportreportsName of the report, for example queries.
X-Site-Idsite reportsThe site the report is about.
X-Period-From, X-Period-Toreports with a periodThe first and last day actually used, YYYY-MM-DD.
X-Data-ThroughreportsThe last day for which data has been synced.
X-Total-CountlistsTotal rows in the full result (not just this page).
X-Page, X-Per-Page, X-Total-Pagespaged listsCurrent page, rows per page and number of pages.
Retry-After429Seconds until you may try again.
WWW-Authenticate401Bearer realm="SEO Signal API"

Responses are sent with Cache-Control: no-store.

Errors

Statuserror.codeWhen
401invalid_api_keyThe key is missing, wrong or revoked.
403account_unavailable, api_not_enabledThe account is locked, disabled or unverified, or is on the free trial or has no active plan.
403scope_not_allowedThe key may not read this product (Rank Tracker or Assistant). Change it under Account → Developer.
404not_foundNo such site, project or endpoint, or it belongs to another account. The two cases look the same on purpose.
405method_not_allowedOnly GET exists on REST; MCP accepts POST only.
409site_not_enabled, no_data_yet, site_requiredSite analysis is off for the site, the first sync has not finished, or no site is connected.
422invalid_parameter, site_requiredA parameter is wrong; details.field names it. site_required means several sites are connected and you must pass site_id.
429daily_limit_reached, rate_limitedDaily limit reached, or more than 120 requests in a minute.
500internal_errorSomething went wrong on our side.
503upstream_unavailableThe data service is temporarily unavailable. Try again in a few minutes.

Limits

  • Daily limit: 1,000 requests per account per day by default (see X-Daily-Limit). Every request counts, including MCP messages and failed requests.
  • Burst limit: 120 requests per minute.
  • Period length: at most 240 days per report. Page size is 10 to 500 rows.

Dates and periods

Search Console data arrives about two days late, so there is no data for “today”. Reports with a period end on the last day with data (data_through). Choose the period in one of two ways:

  • days=28: the 28 days ending on the last day with data (1 to 240, default 28).
  • from=2026-10-01&to=2026-10-31: an exact range. Send both.

The changes report compares the period with the one just before it, and days there is 7, 14, 28, 90 or 180.

Where the data comes from

Every report is answered from SEO Signal’s own database. A request to the API, or a call to an MCP tool, never calls Google. Search Console is read only by our scheduled sync and by actions you take in the dashboard. That means:

  • Asking a thousand questions cannot use up your Search Console quota, and a busy assistant cannot slow your sync down.
  • An answer is as fresh as the last sync. meta.data_through and the X-Data-Through header give the last day with data.
  • A few dashboard features that need Google at the moment you ask are not in the API: the live sitemap list, keyword suggestions for a project, and anything that scans or inspects URLs. For ideas on which queries to add to a project, use the queries report with min_impressions.

REST reference

All endpoints are GET under https://app.seosignal.net/api/v1. {site} and {project} are ids from the sites and projects reports.

EndpointProductWhat it returns
/meany keyThe account, plan, what this key may read, and today’s usage.
/reportsany keyThe reports this key can run, with their parameters.
/sitesAssistant or TrackerList sites. Search Console sites on the account with their status, whether Site analysis and the Rank Tracker are on, and the last day with data.
/sites/{site}/performanceAssistantSite performance. Clicks, impressions, CTR and average position for a site, with the daily series. Optionally for one country or one device.
/sites/{site}/queriesAssistantSearch queries. Queries that brought impressions and clicks, with change against the previous period. Paged.
/sites/{site}/pagesAssistantPages. Pages that brought impressions and clicks, with change against the previous period. Paged.
/sites/{site}/countriesAssistantCountries. Clicks, impressions, CTR and position by country.
/sites/{site}/devicesAssistantDevices. Clicks, impressions, CTR and position by device.
/sites/{site}/changesAssistantWhat changed. Which pages and queries gained or lost the most, comparing the period with the one before it, with likely causes.
/sites/{site}/exploreAssistantExplore a page, folder or query. Performance of one URL, one folder or one query over time, with its related queries or pages.
/sites/{site}/opportunitiesAssistantGrowth opportunities. The ranked task list: striking-distance queries, low-CTR pages, cannibalization and fading content, with estimated clicks.
/sites/{site}/index-healthAssistantIndex health. Index and sitemap summary from URL Inspection: how many URLs are indexed, excluded or have problems.
/sites/{site}/trafficAssistantTraffic report. The client-style traffic summary: totals against the previous period of the same length, the daily series, and the top 10 queries and pages.
/sites/{site}/segmentsAssistantBrand and search intent. Clicks split between brand and non-brand queries (when brand terms are set) and by search intent (question, buying and so on), with the top queries of each.
/sites/{site}/hostsAssistantHosts. Performance by host (the main domain and its subdomains).
/sites/{site}/page-queriesAssistantQueries of one page. The queries that bring a given page impressions and clicks (last 28 days with data, at most 200 rows).
/sites/{site}/index-urlsAssistantIndex status of URLs. URLs known to Index Guard with their index category (indexed, crawled but not indexed, noindex and so on), whether they are in a sitemap and when they were last checked. Paged.
/sites/{site}/client-reportsAssistantClient reports. Client reports created for the site, with their public share links.
/sites/{site}/client-reports/{report_id}AssistantOne client report. The full content of a client report: totals against the previous period, daily series, top queries and pages, countries and devices.
/projectsTrackerRank Tracker projects. Rank Tracker projects on the account with their targets and keyword counts.
/projects/{project}/latestTrackerLatest rank changes. Current position of every keyword in a project and its change since the previous reading.
/projects/{project}/periodTrackerRank changes in a period. Position of every keyword in a project at the start and end of a period, and the change.
/projects/{project}TrackerOne project. A Rank Tracker project: site, targets, status and every keyword with its tags.
/projects/{project}/overviewTrackerProject overview. Every keyword with its position, change, clicks and a short trend, plus how many keywords sit in each position band and how many improved or dropped.
/projects/{project}/matrixTrackerDaily positions. The position of every keyword on every day of the period (the daily history table). The period is limited to 62 days.
/projects/{project}/keywords/{keyword_id}/historyTrackerHistory of one keyword. One keyword of a project: daily position, clicks and impressions, the ranking page and its changes, and best, worst and average position.
/projects/{project}/membersTrackerProject members. The accounts a project is shared with and their roles.
/tagsTrackerKeyword tags. Your tags for organising keywords. Use the ids in the tags parameter of the project reports.

Parameters

ParameterTypeUsed byDescription
categorystringindex_urlsOnly URLs in this category, for example "indexed" or "crawled_not_indexed" (see the counts in index_health).
countrystringperformanceCountry code in lowercase, for example "usa". Cannot be combined with device.
daysintegermany reportsLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
devicestring: desktop | mobile | tabletperformanceDevice. Cannot be combined with country.
dirstring: asc | descqueries, pagesSort direction (default desc).
folderstringpagesOnly pages inside this folder, for example "/blog/".
fromstringmany reportsFirst day, YYYY-MM-DD. Use together with "to".
keyword_idstringproject_keyword_historyKeyword id from project, project_latest or project_period.
limitintegercountriesMost rows to return, 1-250 (default 50).
max_ctrnumberqueries, pagesOnly rows with a click-through rate at or below this value, as a fraction: 0.02 means 2%.
metricstring: clicks | impressions | ctr | positionchangesMetric to compare (default clicks).
min_clicksintegerqueries, pagesOnly rows with at least this many clicks.
min_impressionsintegerqueries, pagesOnly rows with at least this many impressions.
pageintegerqueries, pages, page_queries, index_urlsPage number, starting at 1 (default 1).
per_pageintegerqueries, pages, index_urlsRows per page, 10-500 (default 50).
position_fromnumberqueries, pagesOnly rows whose average position is this number or worse (higher). For example 4 keeps positions 4 and below on the page.
position_tonumberqueries, pagesOnly rows whose average position is this number or better (lower). For example 20 keeps positions 1 to 20.
project_idstringmany reportsRank Tracker project id from the projects report.
qstringqueries, pages, explore, index_urlsOnly rows that contain this text.
report_idstringclient_reportReport id from client_reports.
site_idstringmany reportsSite id from the sites report. Optional when the account has exactly one usable site.
sortstring: clicks | impressions | ctr | position | queryqueries, pagesSort column (default clicks).
tagsstringproject_period, project_matrixComma-separated tag ids. Only keywords with these tags.
target_idstringproject_latest, project_period, project_overview, project_matrix, project_keyword_historyCountry and device target inside the project. Optional.
tostringmany reportsLast day, YYYY-MM-DD.
typestring: url | folder | queryexploreWhat q is.
windowintegerproject_overviewDays compared, 1-28 (default 7).

In REST, site_id, project_id, report_id and keyword_id are part of the path (/sites/{site}/queries); everything else is a query-string parameter. In MCP they are all tool arguments.

In REST, site_id, project_id, report_id and keyword_id are part of the path (/sites/{site}/queries); everything else is a query-string parameter. In MCP they are all tool arguments.

In REST, site_id, project_id, report_id and keyword_id are part of the path (/sites/{site}/queries); everything else is a query-string parameter. In MCP they are all tool arguments.

Example: top queries, page 2

curl -i "https://app.seosignal.net/api/v1/sites/2/queries?days=14&per_page=10&sort=impressions&min_clicks=1" \
  -H "Authorization: Bearer ssk_YOUR_KEY"
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_4k2m9x0c1a7b3d5e8f6g
X-API-Version: 1
X-Daily-Limit: 1000
X-Daily-Remaining: 996
X-Report: queries
X-Site-Id: 2
X-Period-From: 2026-10-31
X-Period-To: 2026-11-13
X-Data-Through: 2026-11-13
X-Total-Count: 6
X-Page: 1
X-Per-Page: 10
X-Total-Pages: 1

{
    "data": [
        {
            "query": "web design",
            "clicks": 883,
            "impressions": 8887,
            "ctr": 0.0994,
            "position": 13.2,
            "intent": "other",
            "previous_position": 12.8,
            "previous_clicks": 845,
            "change": -0.4
        }
    ],
    "meta": {
        "report": "queries",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "period": {
            "from": "2026-10-31",
            "to": "2026-11-13",
            "days": 14
        },
        "data_through": "2026-11-13",
        "pagination": {
            "total": 6,
            "page": 1,
            "per_page": 10,
            "total_pages": 1
        },
        "previous_period_complete": true
    }
}

Loop until X-Page equals X-Total-Pages to read a whole list.

Report reference

Every report below is available as a REST endpoint and as an MCP tool with the same name. The examples are real responses from a test site, shortened: lists show their first item only. Values such as ctr are fractions (0.0993 is 9.93%) and positions are Search Console average positions.

Conventions

  • CTR is a fraction between 0 and 1. Position is the average position (1 is the top); lower is better.
  • Change fields named change are previous minus current position, so a positive number means the item moved up.
  • Ids (id, site_id, project_id…) are strings of digits. Treat them as opaque.
  • Dates are YYYY-MM-DD; timestamps are ISO 8601 in UTC.
  • A value that does not exist (for example no previous-period data) is null, never missing.

List sites sites

GET /api/v1/sites · MCP tool sites · Assistant or Tracker

Search Console sites on the account with their status, whether Site analysis and the Rank Tracker are on, and the last day with data.

No parameters.

Use id as site_id everywhere else. site_analysis is true when Site analysis is switched on (the Assistant reports need it); rank_tracker says whether the Rank Tracker is on. last_data_day is the last day with data.

{
    "data": [
        {
            "id": "2",
            "url": "https://blog.example.ir/",
            "type": "url_prefix",
            "permission_level": "siteFullUser",
            "status": "active",
            "site_analysis": true,
            "rank_tracker": true,
            "last_data_day": "2026-11-13",
            "last_sync_at": "2026-11-15T21:35:57.02748Z",
            "sync_pending": false
        }
    ],
    "meta": {
        "report": "sites",
        "count": 2
    }
}

Site performance performance

GET /api/v1/sites/{site}/performance · MCP tool performance · Assistant

Clicks, impressions, CTR and average position for a site, with the daily series. Optionally for one country or one device.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
daysintegerLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
fromstringFirst day, YYYY-MM-DD. Use together with "to".
tostringLast day, YYYY-MM-DD.
countrystringCountry code in lowercase, for example "usa". Cannot be combined with device.
devicestring: desktop | mobile | tabletDevice. Cannot be combined with country.

totals.position is the average position weighted by impressions. daily has one row per day.

{
    "data": {
        "totals": {
            "clicks": 795,
            "impressions": 7989,
            "ctr": 0.0995,
            "position": 12.09
        },
        "daily": [
            {
                "date": "2026-10-31",
                "clicks": 77,
                "impressions": 772,
                "ctr": 0.0997,
                "position": 10.2
            }
        ]
    },
    "meta": {
        "report": "performance",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "period": {
            "from": "2026-10-31",
            "to": "2026-11-13",
            "days": 14
        },
        "data_through": "2026-11-13",
        "filters": []
    }
}

Search queries queries

GET /api/v1/sites/{site}/queries · MCP tool queries · Assistant

Queries that brought impressions and clicks, with change against the previous period. Paged.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
daysintegerLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
fromstringFirst day, YYYY-MM-DD. Use together with "to".
tostringLast day, YYYY-MM-DD.
pageintegerPage number, starting at 1 (default 1).
per_pageintegerRows per page, 10-500 (default 50).
qstringOnly rows that contain this text.
dirstring: asc | descSort direction (default desc).
min_clicksintegerOnly rows with at least this many clicks.
min_impressionsintegerOnly rows with at least this many impressions.
position_fromnumberOnly rows whose average position is this number or worse (higher). For example 4 keeps positions 4 and below on the page.
position_tonumberOnly rows whose average position is this number or better (lower). For example 20 keeps positions 1 to 20.
max_ctrnumberOnly rows with a click-through rate at or below this value, as a fraction: 0.02 means 2%.
sortstring: clicks | impressions | ctr | position | querySort column (default clicks).

change is previous_position minus position: a positive number means the query moved up. The previous_* fields are null when the previous period has no data for the query, and meta.previous_period_complete says whether the previous period has enough data to compare. intent is the search intent of the query.

{
    "data": [
        {
            "query": "web design",
            "clicks": 883,
            "impressions": 8887,
            "ctr": 0.0994,
            "position": 13.2,
            "intent": "other",
            "previous_position": 12.8,
            "previous_clicks": 845,
            "change": -0.4
        }
    ],
    "meta": {
        "report": "queries",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "period": {
            "from": "2026-10-31",
            "to": "2026-11-13",
            "days": 14
        },
        "data_through": "2026-11-13",
        "pagination": {
            "total": 6,
            "page": 1,
            "per_page": 10,
            "total_pages": 1
        },
        "previous_period_complete": true
    }
}

Pages pages

GET /api/v1/sites/{site}/pages · MCP tool pages · Assistant

Pages that brought impressions and clicks, with change against the previous period. Paged.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
daysintegerLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
fromstringFirst day, YYYY-MM-DD. Use together with "to".
tostringLast day, YYYY-MM-DD.
pageintegerPage number, starting at 1 (default 1).
per_pageintegerRows per page, 10-500 (default 50).
qstringOnly rows that contain this text.
dirstring: asc | descSort direction (default desc).
min_clicksintegerOnly rows with at least this many clicks.
min_impressionsintegerOnly rows with at least this many impressions.
position_fromnumberOnly rows whose average position is this number or worse (higher). For example 4 keeps positions 4 and below on the page.
position_tonumberOnly rows whose average position is this number or better (lower). For example 20 keeps positions 1 to 20.
max_ctrnumberOnly rows with a click-through rate at or below this value, as a fraction: 0.02 means 2%.
sortstring: clicks | impressions | ctr | position | pageSort column (default clicks).
folderstringOnly pages inside this folder, for example "/blog/".

click_change is clicks minus previous_clicks; change is the position change as in queries.

{
    "data": [
        {
            "page": "https://blog.example.ir/pricing",
            "clicks": 919,
            "impressions": 9253,
            "ctr": 0.0993,
            "position": 14.5,
            "previous_clicks": 881,
            "previous_position": 11.1,
            "click_change": 38,
            "change": -3.4
        }
    ],
    "meta": {
        "report": "pages",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "period": {
            "from": "2026-10-31",
            "to": "2026-11-13",
            "days": 14
        },
        "data_through": "2026-11-13",
        "pagination": {
            "total": 3,
            "page": 1,
            "per_page": 10,
            "total_pages": 1
        },
        "previous_period_complete": true
    }
}

Countries countries

GET /api/v1/sites/{site}/countries · MCP tool countries · Assistant

Clicks, impressions, CTR and position by country.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
daysintegerLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
fromstringFirst day, YYYY-MM-DD. Use together with "to".
tostringLast day, YYYY-MM-DD.
limitintegerMost rows to return, 1-250 (default 50).

key is the country code in lowercase.

{
    "data": [
        {
            "key": "irn",
            "clicks": 847,
            "impressions": 8529,
            "ctr": 0.0993,
            "position": 12.4
        }
    ],
    "meta": {
        "report": "countries",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "period": {
            "from": "2026-10-31",
            "to": "2026-11-13",
            "days": 14
        },
        "data_through": "2026-11-13",
        "count": 3
    }
}

Devices devices

GET /api/v1/sites/{site}/devices · MCP tool devices · Assistant

Clicks, impressions, CTR and position by device.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
daysintegerLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
fromstringFirst day, YYYY-MM-DD. Use together with "to".
tostringLast day, YYYY-MM-DD.

key is the device: desktop, mobile or tablet.

{
    "data": [
        {
            "key": "mobile",
            "clicks": 831,
            "impressions": 8363,
            "ctr": 0.0994,
            "position": 13.3
        }
    ],
    "meta": {
        "report": "devices",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "period": {
            "from": "2026-10-31",
            "to": "2026-11-13",
            "days": 14
        },
        "data_through": "2026-11-13",
        "count": 2
    }
}

What changed changes

GET /api/v1/sites/{site}/changes · MCP tool changes · Assistant

Which pages and queries gained or lost the most, comparing the period with the one before it, with likely causes.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
daysintegerLength of each period in days (7, 14, 28, 90 or 180; default 14).
metricstring: clicks | impressions | ctr | positionMetric to compare (default clicks).
tostringLast day of the period, YYYY-MM-DD. Defaults to the last day with data.

Pages and queries are each split into gainers, losers, added (new in the period) and lost (gone from it), with added_count and lost_count. delta is the change in the chosen metric. When ready is false, or needs_history is true, the site does not have enough history yet to compare two periods.

{
    "data": {
        "ready": true,
        "needs_history": false,
        "days": 14,
        "metric": "clicks",
        "end_date": "2026-11-13",
        "from": "2026-10-31",
        "to": "2026-11-13",
        "previous_from": "2026-10-17",
        "previous_to": "2026-10-30",
        "pages": {
            "gainers": [
                {
                    "key": "https://blog.example.ir/pricing",
                    "clicks": 919,
                    "impressions": 9253,
                    "ctr": 0.0993,
                    "position": 14.5,
                    "previous_clicks": 881,
                    "previous_impressions": 8864,
                    "previous_ctr": 0.0994,
                    "previous_position": 11.1,
                    "delta": 38
                }
            ],
            "losers": [
                {
                    "key": "https://blog.example.ir/blog/seo",
                    "clicks": 706,
                    "impressions": 7135,
                    "ctr": 0.0989,
                    "position": 13.4,
                    "previous_clicks": 793,
                    "previous_impressions": 7992,
                    "previous_ctr": 0.0992,
                    "previous_position": 12.9,
                    "delta": -87
                }
            ],
            "added": [],
            "lost": [],
            "added_count": 0,
            "lost_count": 0
        },
        "queries": {
            "gainers": [
                {
                    "key": "web design",
                    "clicks": 883,
                    "impressions": 8887,
                    "ctr": 0.0994,
                    "position": 13.2,
                    "previous_clicks": 845,
                    "previous_impressions": 8526,
                    "previous_ctr": 0.0991,
                    "previous_position": 12.8,
                    "delta": 38
                }
            ],
            "losers": [
                {
                    "key": "keyword research",
                    "clicks": 653,
                    "impressions": 6587,
                    "ctr": 0.0991,
                    "position": 14.3,
                    "previous_clicks": 1052,
                    "previous_impressions": 10578,
                    "previous_ctr": 0.0995,
                    "previous_position": 15.2,
                    "delta": -399
                }
            ],
            "added": [],
            "lost": [],
            "added_count": 0,
            "lost_count": 0
        }
    },
    "meta": {
        "report": "changes",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "period": {
            "from": "2026-10-31",
            "to": "2026-11-13",
            "days": 14
        },
        "data_through": "2026-11-13",
        "metric": "clicks"
    }
}

Explore a page, folder or query explore

GET /api/v1/sites/{site}/explore · MCP tool explore · Assistant

Performance of one URL, one folder or one query over time, with its related queries or pages.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
type (required)string: url | folder | queryWhat q is.
q (required)stringThe URL, folder or query text (800 characters at most).
daysintegerPeriod length in days (default 28).
tostringLast day, YYYY-MM-DD. Defaults to the last day with data.

For a URL or folder, keywords lists its queries; for a query, pages lists its pages. series and previous_series are the daily values of the period and of the one before it. found is false when nothing matches q.

{
    "data": {
        "ready": true,
        "found": true,
        "type": "url",
        "query": "https://blog.example.ir/pricing",
        "label": "blog.example.ir/pricing",
        "days": 28,
        "end_date": "2026-11-13",
        "from": "2026-10-17",
        "to": "2026-11-13",
        "previous_from": "2026-09-19",
        "previous_to": "2026-10-16",
        "previous_complete": true,
        "current": {
            "clicks": 1800,
            "impressions": 18117,
            "ctr": 0.0994,
            "position": 12.8
        },
        "previous": {
            "clicks": 1813,
            "impressions": 18248,
            "ctr": 0.0994,
            "position": 12.2
        },
        "series": [
            {
                "date": "2026-10-17",
                "clicks": 37,
                "impressions": 370,
                "position": 10
            }
        ],
        "previous_series": [
            {
                "date": "2026-09-19",
                "clicks": 72,
                "impressions": 728,
                "position": 5.8
            }
        ],
        "page_count": 1,
        "detail": {
            "days": 28,
            "from": "2026-10-17",
            "to": "2026-11-13",
            "previous_from": "2026-09-19",
            "previous_to": "2026-10-16",
            "clamped": false,
            "previous_complete": true
        },
        "pages": [
            {
                "page": "https://blog.example.ir/pricing",
                "clicks": 1800,
                "impressions": 18117,
                "ctr": 0.0994,
                "position": 12.8,
                "previous_clicks": 1813,
                "previous_impressions": 18248,
                "previous_position": 12.2
            }
        ],
        "keywords": [
            {
                "query": "rank tracker",
                "clicks": 1920,
                "impressions": 19335,
                "ctr": 0.0993,
                "position": 11.7,
                "previous_clicks": 0,
                "previous_impressions": 0,
                "previous_position": null
            }
        ],
        "lost_keywords": [],
        "keyword_count": 6,
        "related": [],
        "tracked": false
    },
    "meta": {
        "report": "explore",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "data_through": "2026-11-13",
        "query": {
            "type": "url",
            "q": "https://blog.example.ir/pricing",
            "days": 28
        }
    }
}

Growth opportunities opportunities

GET /api/v1/sites/{site}/opportunities · MCP tool opportunities · Assistant

The ranked task list: striking-distance queries, low-CTR pages, cannibalization and fading content, with estimated clicks.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.

Sections: striking_distance (positions just off page one), low_ctr, cannibalization (one query spread over several pages, each with its share), decay (fading pages) and lost. Each item has a priority. *_needs_history flags say a section needs more history.

{
    "data": {
        "ready": true,
        "end_date": "2026-11-13",
        "lost": [],
        "lost_needs_history": false,
        "decay_needs_history": false,
        "striking_distance": [
            {
                "query": "web design",
                "page": "https://blog.example.ir/blog/seo",
                "position": 13.2,
                "impressions": 8887,
                "clicks": 883,
                "priority": "high"
            }
        ],
        "low_ctr": [],
        "cannibalization": [
            {
                "query": "rank tracker",
                "impressions": 25985,
                "clicks": 2581,
                "pages": [
                    {
                        "page": "https://blog.example.ir/",
                        "impressions": 9701,
                        "clicks": 965,
                        "position": 14.1,
                        "share": 0.37
                    }
                ],
                "priority": "high"
            }
        ],
        "decay": []
    },
    "meta": {
        "report": "opportunities",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "data_through": "2026-11-13"
    }
}

Index health index_health

GET /api/v1/sites/{site}/index-health · MCP tool index_health · Assistant

Index and sitemap summary from URL Inspection: how many URLs are indexed, excluded or have problems.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.

counts has one number per index category; use a category name as the category parameter of index_urls. remaining_today and daily_budget are Google's URL Inspection quota for the site.

{
    "data": {
        "total": 0,
        "in_sitemap": 0,
        "problem_in_sitemap": 0,
        "remaining_today": 1000,
        "daily_budget": 1000,
        "max_urls": 5000,
        "resets_at": "2026-11-17T00:00:00Z",
        "counts": {
            "unchecked": 0,
            "serving": 0,
            "indexed": 0,
            "crawled_not_indexed": 0,
            "discovered_not_indexed": 0,
            "unknown_to_google": 0,
            "noindex": 0,
            "blocked_robots": 0,
            "canonical_other": 0,
            "redirect": 0,
            "not_found": 0,
            "fetch_error": 0,
            "other": 0,
            "error": 0
        },
        "scan": null,
        "events": []
    },
    "meta": {
        "report": "index_health",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "data_through": "2026-11-13"
    }
}

Traffic report traffic

GET /api/v1/sites/{site}/traffic · MCP tool traffic · Assistant

The client-style traffic summary: totals against the previous period of the same length, the daily series, and the top 10 queries and pages.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
daysintegerLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
fromstringFirst day, YYYY-MM-DD. Use together with "to".
tostringLast day, YYYY-MM-DD.

Compare totals with previous_totals (the period of the same length just before, see meta.previous_period). top_queries and top_pages hold the top 10 by clicks.

{
    "data": {
        "totals": {
            "clicks": 795,
            "impressions": 7989,
            "ctr": 0.0995,
            "position": 12.09
        },
        "previous_totals": {
            "clicks": 666,
            "impressions": 6726,
            "ctr": 0.099,
            "position": 12.68
        },
        "daily": [
            {
                "date": "2026-10-31",
                "clicks": 77,
                "impressions": 772,
                "ctr": 0.0997,
                "position": 10.2
            }
        ],
        "previous_daily": [
            {
                "date": "2026-10-17",
                "clicks": 82,
                "impressions": 821,
                "ctr": 0.0999,
                "position": 15.1
            }
        ],
        "top_queries": [
            {
                "query": "web design",
                "clicks": 883,
                "impressions": 8887,
                "ctr": 0.0994,
                "position": 13.22
            }
        ],
        "top_pages": [
            {
                "page": "https://blog.example.ir/pricing",
                "clicks": 919,
                "impressions": 9253,
                "ctr": 0.0993,
                "position": 14.47
            }
        ]
    },
    "meta": {
        "report": "traffic",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "period": {
            "from": "2026-10-31",
            "to": "2026-11-13",
            "days": 14
        },
        "data_through": "2026-11-13",
        "previous_period": {
            "from": "2026-10-17",
            "to": "2026-10-30"
        }
    }
}

Brand and search intent segments

GET /api/v1/sites/{site}/segments · MCP tool segments · Assistant

Clicks split between brand and non-brand queries (when brand terms are set) and by search intent (question, buying and so on), with the top queries of each.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
daysintegerLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
fromstringFirst day, YYYY-MM-DD. Use together with "to".
tostringLast day, YYYY-MM-DD.

intents splits queries by search intent. brand is filled only when brand terms are set (brand_configured), and then splits clicks between brand and non-brand queries.

{
    "data": {
        "from": "2026-10-17",
        "to": "2026-11-13",
        "previous_complete": true,
        "brand_configured": false,
        "terms": [],
        "brand": null,
        "intents": [
            {
                "key": "question",
                "label": "Question",
                "queries": 0,
                "clicks": 0,
                "impressions": 0,
                "previous_clicks": 0,
                "top": []
            }
        ]
    },
    "meta": {
        "report": "segments",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "period": {
            "from": "2026-10-17",
            "to": "2026-11-13",
            "days": 28
        },
        "data_through": "2026-11-13"
    }
}

Hosts hosts

GET /api/v1/sites/{site}/hosts · MCP tool hosts · Assistant

Performance by host (the main domain and its subdomains).

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
daysintegerLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
fromstringFirst day, YYYY-MM-DD. Use together with "to".
tostringLast day, YYYY-MM-DD.

One row per host (the main domain and its subdomains) with the number of pages that got impressions.

{
    "data": [
        {
            "host": "blog.example.ir",
            "clicks": 4835,
            "impressions": 48731,
            "ctr": 0.0992,
            "position": 12.92,
            "pages": 3
        }
    ],
    "meta": {
        "report": "hosts",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "period": {
            "from": "2026-10-17",
            "to": "2026-11-13",
            "days": 28
        },
        "data_through": "2026-11-13",
        "count": 1
    }
}

Queries of one page page_queries

GET /api/v1/sites/{site}/page-queries · MCP tool page_queries · Assistant

The queries that bring a given page impressions and clicks (last 28 days with data, at most 200 rows).

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
page (required)stringFull page address, for example https://example.com/blog/post.

The queries for one page over the last 28 days with data, best first, at most 200. The page is matched by its path, so write it as Search Console reports it.

{
    "data": [
        {
            "query": "rank tracker",
            "clicks": 1920,
            "impressions": 19335,
            "position": 11.7
        }
    ],
    "meta": {
        "report": "page_queries",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "data_through": "2026-11-13",
        "page": "https://blog.example.ir/pricing",
        "count": 6
    }
}

Index status of URLs index_urls

GET /api/v1/sites/{site}/index-urls · MCP tool index_urls · Assistant

URLs known to Index Guard with their index category (indexed, crawled but not indexed, noindex and so on), whether they are in a sitemap and when they were last checked. Paged.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
categorystringOnly URLs in this category, for example "indexed" or "crawled_not_indexed" (see the counts in index_health).
qstringOnly URLs that contain this text.
pageintegerPage number, starting at 1 (default 1).
per_pageintegerRows per page, 10-500 (default 100).

category is the index status of the URL, in_sitemap says whether a sitemap lists it, and canonical_mismatch with google_canonical shows when Google picked another canonical. The list is empty until Index Guard has scanned the site.

{
    "data": [],
    "meta": {
        "report": "index_urls",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "data_through": "2026-11-13",
        "pagination": {
            "total": 0,
            "page": 1,
            "per_page": 10,
            "total_pages": 1
        }
    }
}

Client reports client_reports

GET /api/v1/sites/{site}/client-reports · MCP tool client_reports · Assistant

Client reports created for the site, with their public share links.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.

share_url is the public link of the report. Anyone with the link can read it, so treat it as private.

{
    "data": [
        {
            "id": "1",
            "title": "Demo report",
            "brand_name": "Acme",
            "brand_color": "#3A1078",
            "period_days": 28,
            "intro": "Hello",
            "created_at": "2026-11-16T02:27:15.957399Z",
            "share_url": "http://127.0.0.1:8767/r/952dd488d821310fd11ffd4b680647de67b6b9c5f1a508f6"
        }
    ],
    "meta": {
        "report": "client_reports",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "data_through": "2026-11-13",
        "count": 1
    }
}

One client report client_report

GET /api/v1/sites/{site}/client-reports/{report_id} · MCP tool client_report · Assistant

The full content of a client report: totals against the previous period, daily series, top queries and pages, countries and devices.

ParameterTypeDescription
site_id (in the path)stringSite id from the sites report. Optional when the account has exactly one usable site.
report_id (required) (in the path)stringReport id from client_reports.

The same content as the public report page. daily and previous_daily are the current and previous period.

{
    "data": {
        "ready": true,
        "title": "Demo report",
        "brand_name": "Acme",
        "brand_color": "#3A1078",
        "site": "https://blog.example.ir/",
        "period_days": 28,
        "from": "2026-10-17",
        "to": "2026-11-13",
        "previous_from": "2026-09-19",
        "previous_to": "2026-10-16",
        "totals": {
            "clicks": 1461,
            "impressions": 14715,
            "ctr": 0.0993,
            "position": 12.4
        },
        "previous_totals": {
            "clicks": 1504,
            "impressions": 15208,
            "ctr": 0.0989,
            "position": 11
        },
        "previous_complete": true,
        "daily": [
            {
                "date": "2026-10-17",
                "clicks": 82,
                "impressions": 821
            }
        ],
        "previous_daily": [
            {
                "date": "2026-09-19",
                "clicks": 96,
                "impressions": 963
            }
        ],
        "intro": "Hello",
        "top_queries": [
            {
                "key": "web design",
                "clicks": 1728,
                "impressions": 17413,
                "ctr": 0.0992,
                "previous_clicks": 1612
            }
        ],
        "top_pages": [
            {
                "key": "https://blog.example.ir/pricing",
                "clicks": 1800,
                "impressions": 18117,
                "ctr": 0.0994,
                "previous_clicks": 1813
            }
        ],
        "countries": [
            {
                "key": "irn",
                "clicks": 1684,
                "impressions": 16969
            }
        ],
        "devices": [
            {
                "key": "mobile",
                "clicks": 1606,
                "impressions": 16185
            }
        ],
        "brand": null
    },
    "meta": {
        "report": "client_report",
        "site": {
            "id": "2",
            "url": "https://blog.example.ir/"
        },
        "period": {
            "from": "2026-10-17",
            "to": "2026-11-13",
            "days": 28
        },
        "data_through": "2026-11-13"
    }
}

Rank Tracker projects projects

GET /api/v1/projects · MCP tool projects · Tracker

Rank Tracker projects on the account with their targets and keyword counts.

No parameters.

id is the project_id for the other project reports; targets are the country and device combinations tracked.

{
    "data": [
        {
            "id": "1",
            "name": "Demo",
            "site_id": "2",
            "site_url": "https://blog.example.ir/",
            "host": "blog.example.ir",
            "path_prefix": null,
            "status": "active",
            "keywords": 5,
            "last_data_day": "2026-11-14",
            "targets": [
                {
                    "id": "1",
                    "country": "usa",
                    "device": "desktop"
                }
            ]
        }
    ],
    "meta": {
        "report": "projects",
        "count": 1
    }
}

Latest rank changes project_latest

GET /api/v1/projects/{project}/latest · MCP tool project_latest · Tracker

Current position of every keyword in a project and its change since the previous reading.

ParameterTypeDescription
project_id (required) (in the path)stringRank Tracker project id from the projects report.
target_idstringCountry and device target inside the project. Optional.

Position on the latest day (date) against the previous reading (previous_date). page_changed is true when a different page ranks now.

{
    "data": {
        "ready": true,
        "date": "2026-11-14",
        "previous_date": "2026-11-13",
        "targets": [
            {
                "id": "1",
                "country": "usa",
                "device": "desktop"
            }
        ],
        "target": 1,
        "items": [
            {
                "id": "1",
                "keyword": "web design",
                "tags": [],
                "position": 16.4,
                "previous_position": 14.9,
                "change": -1.5,
                "state": "ok",
                "clicks": 63,
                "impressions": 634,
                "page": "https://blog.example.ir/",
                "previous_page": "https://blog.example.ir/pricing",
                "page_changed": true
            }
        ],
        "distribution": [
            {
                "key": "r1",
                "count": 0
            }
        ],
        "movement": {
            "improved": 0,
            "dropped": 5,
            "stable": 0,
            "new": 0,
            "lost": 0
        }
    },
    "meta": {
        "report": "project_latest",
        "project": {
            "id": "1",
            "name": "Demo"
        },
        "data_through": "2026-11-14",
        "count": 5
    }
}

Rank changes in a period project_period

GET /api/v1/projects/{project}/period · MCP tool project_period · Tracker

Position of every keyword in a project at the start and end of a period, and the change.

ParameterTypeDescription
project_id (required) (in the path)stringRank Tracker project id from the projects report.
target_idstringCountry and device target inside the project. Optional.
daysintegerLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
fromstringFirst day, YYYY-MM-DD. Use together with "to".
tostringLast day, YYYY-MM-DD.
tagsstringComma-separated tag ids. Only keywords with these tags.

Each keyword with its position at the start and end of the period, change (positive means it moved up), the average and days_ranked. series is the project-wide daily trend.

{
    "data": {
        "ready": true,
        "from": "2026-11-01",
        "to": "2026-11-14",
        "targets": [
            {
                "id": "1",
                "country": "usa",
                "device": "desktop"
            }
        ],
        "target": 1,
        "items": [
            {
                "id": "1",
                "keyword": "web design",
                "tags": [],
                "start_position": 16,
                "start_date": "2026-11-01",
                "end_position": 16.4,
                "end_date": "2026-11-14",
                "change": -0.4,
                "state": "ok",
                "average": 13.4,
                "impressions": 9111,
                "clicks": 905,
                "days_ranked": 14,
                "page": "https://blog.example.ir/",
                "band": "r30"
            }
        ],
        "distribution": [
            {
                "key": "r1",
                "count": 0
            }
        ],
        "movement": {
            "improved": 1,
            "dropped": 4,
            "stable": 0
        },
        "series": {
            "dates": [
                "2026-11-01"
            ],
            "position": [
                13.05
            ],
            "presence": [
                100
            ],
            "impressions": [
                3418
            ],
            "clicks": [
                340
            ]
        }
    },
    "meta": {
        "report": "project_period",
        "project": {
            "id": "1",
            "name": "Demo"
        },
        "period": {
            "from": "2026-11-01",
            "to": "2026-11-14",
            "days": 14
        },
        "data_through": "2026-11-14"
    }
}

One project project

GET /api/v1/projects/{project} · MCP tool project · Tracker

A Rank Tracker project: site, targets, status and every keyword with its tags.

ParameterTypeDescription
project_id (required) (in the path)stringRank Tracker project id from the projects report.

Every keyword of the project with its tags. Use a keyword id as keyword_id in project_keyword_history.

{
    "data": {
        "id": "1",
        "name": "Demo",
        "property_id": "2",
        "site_url": "https://blog.example.ir/",
        "property_status": "active",
        "host": "blog.example.ir",
        "path_prefix": null,
        "status": "active",
        "report_frequency": "none",
        "report_email": null,
        "last_synced_date": "2026-11-14",
        "created_at": "2026-11-16T02:26:37.892141Z",
        "role": "owner",
        "targets": [
            {
                "id": "1",
                "country": "usa",
                "device": "desktop"
            }
        ],
        "keywords": [
            {
                "id": "1",
                "keyword": "web design",
                "target_page": null,
                "tags": []
            }
        ],
        "pending_jobs": 0
    },
    "meta": {
        "report": "project",
        "project": {
            "id": "1",
            "name": "Demo"
        },
        "data_through": "2026-11-14"
    }
}

Project overview project_overview

GET /api/v1/projects/{project}/overview · MCP tool project_overview · Tracker

Every keyword with its position, change, clicks and a short trend, plus how many keywords sit in each position band and how many improved or dropped.

ParameterTypeDescription
project_id (required) (in the path)stringRank Tracker project id from the projects report.
target_idstringCountry and device target inside the project. Optional.
windowintegerDays compared, 1-28 (default 7).

items have the current position, previous_position, change (positive means it moved up), clicks and a short trend. distribution counts keywords per position band and movement counts improved, dropped, stable, new and lost keywords.

{
    "data": {
        "ready": true,
        "end_date": "2026-11-14",
        "window": 7,
        "targets": [
            {
                "id": "1",
                "country": "usa",
                "device": "desktop"
            }
        ],
        "target": 1,
        "items": [
            {
                "id": "1",
                "keyword": "web design",
                "tags": [],
                "target_page": null,
                "position": 12.5,
                "previous_position": 14.2,
                "change": 1.7,
                "state": "ok",
                "clicks": 415,
                "impressions": 4184,
                "ctr": 0.0992,
                "trend": [
                    16
                ]
            }
        ],
        "distribution": [
            {
                "key": "top3",
                "count": 0
            }
        ],
        "movement": {
            "improved": 3,
            "dropped": 2,
            "stable": 0,
            "new": 0,
            "lost": 0
        }
    },
    "meta": {
        "report": "project_overview",
        "project": {
            "id": "1",
            "name": "Demo"
        },
        "data_through": "2026-11-14"
    }
}

Daily positions project_matrix

GET /api/v1/projects/{project}/matrix · MCP tool project_matrix · Tracker

The position of every keyword on every day of the period (the daily history table). The period is limited to 62 days.

ParameterTypeDescription
project_id (required) (in the path)stringRank Tracker project id from the projects report.
target_idstringCountry and device target inside the project. Optional.
daysintegerLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
fromstringFirst day, YYYY-MM-DD. Use together with "to".
tostringLast day, YYYY-MM-DD.
tagsstringComma-separated tag ids. Only keywords with these tags.

positions has one value per entry of dates, in the same order; a day without a position is null. The period is limited to 62 days (clamped says so).

{
    "data": {
        "ready": true,
        "from": "2026-11-01",
        "to": "2026-11-14",
        "clamped": false,
        "max_days": 62,
        "targets": [
            {
                "id": "1",
                "country": "usa",
                "device": "desktop"
            }
        ],
        "target": 1,
        "dates": [
            "2026-11-01"
        ],
        "items": [
            {
                "id": "1",
                "keyword": "web design",
                "tags": [],
                "positions": [
                    16
                ],
                "average": 13.4,
                "impressions": 9111,
                "clicks": 905,
                "change": -0.4
            }
        ]
    },
    "meta": {
        "report": "project_matrix",
        "project": {
            "id": "1",
            "name": "Demo"
        },
        "period": {
            "from": "2026-11-01",
            "to": "2026-11-14",
            "days": 14
        },
        "data_through": "2026-11-14"
    }
}

History of one keyword project_keyword_history

GET /api/v1/projects/{project}/keywords/{keyword_id}/history · MCP tool project_keyword_history · Tracker

One keyword of a project: daily position, clicks and impressions, the ranking page and its changes, and best, worst and average position.

ParameterTypeDescription
project_id (required) (in the path)stringRank Tracker project id from the projects report.
target_idstringCountry and device target inside the project. Optional.
keyword_id (required) (in the path)stringKeyword id from project, project_latest or project_period.
daysintegerLength of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given.
fromstringFirst day, YYYY-MM-DD. Use together with "to".
tostringLast day, YYYY-MM-DD.

daily is the day-by-day position with the ranking page; stats summarises it; pages lists the pages that ranked and for how many days.

{
    "data": {
        "id": "1",
        "keyword": "web design",
        "target_page": null,
        "tags": [],
        "target": 1,
        "from": "2026-11-01",
        "to": "2026-11-14",
        "daily": [
            {
                "date": "2026-11-01",
                "clicks": 83,
                "impressions": 830,
                "position": 16,
                "page": "https://blog.example.ir/blog/seo",
                "page_changed": false
            }
        ],
        "stats": {
            "average": 13.4,
            "best": 7.7,
            "worst": 21.5,
            "start": 16,
            "end": 16.4,
            "change": -0.4,
            "clicks": 905,
            "impressions": 9111,
            "days_ranked": 14
        },
        "pages": [
            {
                "page": "https://blog.example.ir/blog/seo",
                "days": 7,
                "clicks": 361,
                "impressions": 3639,
                "position": 13.3,
                "first_date": "2026-11-01",
                "last_date": "2026-11-12"
            }
        ],
        "page_changes": 6,
        "notes": []
    },
    "meta": {
        "report": "project_keyword_history",
        "project": {
            "id": "1",
            "name": "Demo"
        },
        "period": {
            "from": "2026-11-01",
            "to": "2026-11-14",
            "days": 14
        },
        "data_through": "2026-11-14"
    }
}

Project members project_members

GET /api/v1/projects/{project}/members · MCP tool project_members · Tracker

The accounts a project is shared with and their roles.

ParameterTypeDescription
project_id (required) (in the path)stringRank Tracker project id.

The accounts the project is shared with. user_id is the account id.

{
    "data": [
        {
            "user_id": 1,
            "role": "owner"
        }
    ],
    "meta": {
        "report": "project_members",
        "project": {
            "id": "1",
            "name": "Demo"
        },
        "count": 1
    }
}

Keyword tags tags

GET /api/v1/tags · MCP tool tags · Tracker

Your tags for organising keywords. Use the ids in the tags parameter of the project reports.

No parameters.

Your keyword tags. Pass the ids as tags to the project reports.

{
    "data": [],
    "meta": {
        "report": "tags",
        "count": 0
    }
}

MCP: ask your AI assistant

MCP (Model Context Protocol) lets an AI assistant call tools. SEO Signal runs a remote, read-only MCP server that gives the assistant one tool per report, so it can answer “which pages lost the most clicks, and why?” from your real data instead of guessing.

Server addresshttps://app.seosignal.net/api/mcp?token=ssk_YOUR_KEY
TransportStreamable HTTP (JSON-RPC 2.0). POST only; every reply is plain JSON; no session is kept.
Protocol versions2025-06-18, 2025-03-26, 2024-11-05
AuthenticationThe key in the token query parameter, or an Authorization: Bearer header if your client can send one.

Connect a client

In an assistant that takes a remote MCP server by address (for example a custom connector), paste the address above. For a client configured with a JSON file:

{
  "mcpServers": {
    "seosignal": {
      "url": "https://app.seosignal.net/api/mcp?token=ssk_YOUR_KEY"
    }
  }
}

For Claude Code:

claude mcp add --transport http seosignal "https://app.seosignal.net/api/mcp?token=ssk_YOUR_KEY"

Clients differ in how they name this setting. If yours only supports local (stdio) servers, use a small bridge such as mcp-remote pointed at the same address.

Then ask in plain language: “Compare the last 28 days with the 28 before for example.com and list the pages that lost the most clicks.” The assistant picks the tools; your account’s daily limit counts every call.

Choose what the assistant can see

Under Account → Developer you can allow the Search Console Assistant, the Rank Tracker, or both, and switch MCP on or off. MCP needs at least one product enabled. The assistant is shown only the tools your key allows, and a change applies from the next request.

MCP tools

Each tool has the same name, parameters and numbers as the REST report of the same name, and is marked read-only. Tool results are returned as JSON text with the same data and meta as REST.

ToolProductUse it to…
sitesAssistant or TrackerList sites
performanceAssistantSite performance
queriesAssistantSearch queries
pagesAssistantPages
countriesAssistantCountries
devicesAssistantDevices
changesAssistantWhat changed
exploreAssistantExplore a page, folder or query
opportunitiesAssistantGrowth opportunities
index_healthAssistantIndex health
trafficAssistantTraffic report
segmentsAssistantBrand and search intent
hostsAssistantHosts
page_queriesAssistantQueries of one page
index_urlsAssistantIndex status of URLs
client_reportsAssistantClient reports
client_reportAssistantOne client report
projectsTrackerRank Tracker projects
project_latestTrackerLatest rank changes
project_periodTrackerRank changes in a period
projectTrackerOne project
project_overviewTrackerProject overview
project_matrixTrackerDaily positions
project_keyword_historyTrackerHistory of one keyword
project_membersTrackerProject members
tagsTrackerKeyword tags

Errors in MCP. A problem with a tool call (a wrong parameter, a site that is not yours) comes back as a normal tool result with isError: true and the same code and message as REST, so the assistant can read it and correct itself. Protocol problems use JSON-RPC errors (-32700 invalid JSON, -32601 unknown method, -32602 bad parameters). MCP switched off for the key returns HTTP 403.

Security

  • Read-only. No endpoint or tool can add, edit or delete anything, or submit URLs to Google.
  • Your data only. A key reaches only the sites and projects of the account it belongs to. Asking for anyone else’s returns 404.
  • Treat the MCP address like a password. A key in a URL can be saved by the tool that uses it, or appear in logs. Use a client setting that hides it where possible, never post it in a public place, and replace the key under Account → Developer if it leaks. Replacing or revoking stops the old key at once.
  • No hidden sharing. SEO Signal never sends your data to an AI provider by itself. What an assistant does with an answer follows the terms of its own provider. See our Privacy Policy and Google API Disclosure.

Changelog

DateVersionChange
16 Nov 20261First release: 28 read-only reports over REST and MCP (Search Console Assistant and Rank Tracker), the standard envelope and X-* headers, key access choices, and an MCP server that takes the key in the query string.

Questions or a report you need? Write to [email protected].