https://app.seosignal.net.Quick start
- 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. - Choose what it may read: the Search Console Assistant, the Rank Tracker, or both, and switch MCP on or off.
- 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
| Where | How 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.
| Header | Sent on | Meaning |
|---|---|---|
X-Request-Id | every response | Id 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-Version | every response | API version, currently 1. |
X-Daily-Limit | authenticated | Requests allowed per day for the account. |
X-Daily-Remaining | authenticated | Requests left today. The count resets at midnight, server time. |
X-Report | reports | Name of the report, for example queries. |
X-Site-Id | site reports | The site the report is about. |
X-Period-From, X-Period-To | reports with a period | The first and last day actually used, YYYY-MM-DD. |
X-Data-Through | reports | The last day for which data has been synced. |
X-Total-Count | lists | Total rows in the full result (not just this page). |
X-Page, X-Per-Page, X-Total-Pages | paged lists | Current page, rows per page and number of pages. |
Retry-After | 429 | Seconds until you may try again. |
WWW-Authenticate | 401 | Bearer realm="SEO Signal API" |
Responses are sent with Cache-Control: no-store.
Errors
| Status | error.code | When |
|---|---|---|
| 401 | invalid_api_key | The key is missing, wrong or revoked. |
| 403 | account_unavailable, api_not_enabled | The account is locked, disabled or unverified, or is on the free trial or has no active plan. |
| 403 | scope_not_allowed | The key may not read this product (Rank Tracker or Assistant). Change it under Account → Developer. |
| 404 | not_found | No such site, project or endpoint, or it belongs to another account. The two cases look the same on purpose. |
| 405 | method_not_allowed | Only GET exists on REST; MCP accepts POST only. |
| 409 | site_not_enabled, no_data_yet, site_required | Site analysis is off for the site, the first sync has not finished, or no site is connected. |
| 422 | invalid_parameter, site_required | A parameter is wrong; details.field names it. site_required means several sites are connected and you must pass site_id. |
| 429 | daily_limit_reached, rate_limited | Daily limit reached, or more than 120 requests in a minute. |
| 500 | internal_error | Something went wrong on our side. |
| 503 | upstream_unavailable | The 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_throughand theX-Data-Throughheader 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
queriesreport withmin_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.
| Endpoint | Product | What it returns |
|---|---|---|
/me | any key | The account, plan, what this key may read, and today’s usage. |
/reports | any key | The reports this key can run, with their parameters. |
/sites | Assistant or Tracker | List 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}/performance | Assistant | Site performance. Clicks, impressions, CTR and average position for a site, with the daily series. Optionally for one country or one device. |
/sites/{site}/queries | Assistant | Search queries. Queries that brought impressions and clicks, with change against the previous period. Paged. |
/sites/{site}/pages | Assistant | Pages. Pages that brought impressions and clicks, with change against the previous period. Paged. |
/sites/{site}/countries | Assistant | Countries. Clicks, impressions, CTR and position by country. |
/sites/{site}/devices | Assistant | Devices. Clicks, impressions, CTR and position by device. |
/sites/{site}/changes | Assistant | What changed. Which pages and queries gained or lost the most, comparing the period with the one before it, with likely causes. |
/sites/{site}/explore | Assistant | Explore a page, folder or query. Performance of one URL, one folder or one query over time, with its related queries or pages. |
/sites/{site}/opportunities | Assistant | Growth opportunities. The ranked task list: striking-distance queries, low-CTR pages, cannibalization and fading content, with estimated clicks. |
/sites/{site}/index-health | Assistant | Index health. Index and sitemap summary from URL Inspection: how many URLs are indexed, excluded or have problems. |
/sites/{site}/traffic | Assistant | Traffic 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}/segments | Assistant | Brand 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}/hosts | Assistant | Hosts. Performance by host (the main domain and its subdomains). |
/sites/{site}/page-queries | Assistant | Queries 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-urls | Assistant | Index 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-reports | Assistant | Client reports. Client reports created for the site, with their public share links. |
/sites/{site}/client-reports/{report_id} | Assistant | One client report. The full content of a client report: totals against the previous period, daily series, top queries and pages, countries and devices. |
/projects | Tracker | Rank Tracker projects. Rank Tracker projects on the account with their targets and keyword counts. |
/projects/{project}/latest | Tracker | Latest rank changes. Current position of every keyword in a project and its change since the previous reading. |
/projects/{project}/period | Tracker | Rank changes in a period. Position of every keyword in a project at the start and end of a period, and the change. |
/projects/{project} | Tracker | One project. A Rank Tracker project: site, targets, status and every keyword with its tags. |
/projects/{project}/overview | Tracker | Project 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}/matrix | Tracker | Daily 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}/history | Tracker | History 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}/members | Tracker | Project members. The accounts a project is shared with and their roles. |
/tags | Tracker | Keyword tags. Your tags for organising keywords. Use the ids in the tags parameter of the project reports. |
Parameters
| Parameter | Type | Used by | Description |
|---|---|---|---|
category | string | index_urls | Only URLs in this category, for example "indexed" or "crawled_not_indexed" (see the counts in index_health). |
country | string | performance | Country code in lowercase, for example "usa". Cannot be combined with device. |
days | integer | many reports | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
device | string: desktop | mobile | tablet | performance | Device. Cannot be combined with country. |
dir | string: asc | desc | queries, pages | Sort direction (default desc). |
folder | string | pages | Only pages inside this folder, for example "/blog/". |
from | string | many reports | First day, YYYY-MM-DD. Use together with "to". |
keyword_id | string | project_keyword_history | Keyword id from project, project_latest or project_period. |
limit | integer | countries | Most rows to return, 1-250 (default 50). |
max_ctr | number | queries, pages | Only rows with a click-through rate at or below this value, as a fraction: 0.02 means 2%. |
metric | string: clicks | impressions | ctr | position | changes | Metric to compare (default clicks). |
min_clicks | integer | queries, pages | Only rows with at least this many clicks. |
min_impressions | integer | queries, pages | Only rows with at least this many impressions. |
page | integer | queries, pages, page_queries, index_urls | Page number, starting at 1 (default 1). |
per_page | integer | queries, pages, index_urls | Rows per page, 10-500 (default 50). |
position_from | number | queries, pages | Only rows whose average position is this number or worse (higher). For example 4 keeps positions 4 and below on the page. |
position_to | number | queries, pages | Only rows whose average position is this number or better (lower). For example 20 keeps positions 1 to 20. |
project_id | string | many reports | Rank Tracker project id from the projects report. |
q | string | queries, pages, explore, index_urls | Only rows that contain this text. |
report_id | string | client_report | Report id from client_reports. |
site_id | string | many reports | Site id from the sites report. Optional when the account has exactly one usable site. |
sort | string: clicks | impressions | ctr | position | query | queries, pages | Sort column (default clicks). |
tags | string | project_period, project_matrix | Comma-separated tag ids. Only keywords with these tags. |
target_id | string | project_latest, project_period, project_overview, project_matrix, project_keyword_history | Country and device target inside the project. Optional. |
to | string | many reports | Last day, YYYY-MM-DD. |
type | string: url | folder | query | explore | What q is. |
window | integer | project_overview | Days 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
changearepreviousminuscurrentposition, 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
days | integer | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
from | string | First day, YYYY-MM-DD. Use together with "to". |
to | string | Last day, YYYY-MM-DD. |
country | string | Country code in lowercase, for example "usa". Cannot be combined with device. |
device | string: desktop | mobile | tablet | Device. 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
days | integer | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
from | string | First day, YYYY-MM-DD. Use together with "to". |
to | string | Last day, YYYY-MM-DD. |
page | integer | Page number, starting at 1 (default 1). |
per_page | integer | Rows per page, 10-500 (default 50). |
q | string | Only rows that contain this text. |
dir | string: asc | desc | Sort direction (default desc). |
min_clicks | integer | Only rows with at least this many clicks. |
min_impressions | integer | Only rows with at least this many impressions. |
position_from | number | Only rows whose average position is this number or worse (higher). For example 4 keeps positions 4 and below on the page. |
position_to | number | Only rows whose average position is this number or better (lower). For example 20 keeps positions 1 to 20. |
max_ctr | number | Only rows with a click-through rate at or below this value, as a fraction: 0.02 means 2%. |
sort | string: clicks | impressions | ctr | position | query | Sort 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
days | integer | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
from | string | First day, YYYY-MM-DD. Use together with "to". |
to | string | Last day, YYYY-MM-DD. |
page | integer | Page number, starting at 1 (default 1). |
per_page | integer | Rows per page, 10-500 (default 50). |
q | string | Only rows that contain this text. |
dir | string: asc | desc | Sort direction (default desc). |
min_clicks | integer | Only rows with at least this many clicks. |
min_impressions | integer | Only rows with at least this many impressions. |
position_from | number | Only rows whose average position is this number or worse (higher). For example 4 keeps positions 4 and below on the page. |
position_to | number | Only rows whose average position is this number or better (lower). For example 20 keeps positions 1 to 20. |
max_ctr | number | Only rows with a click-through rate at or below this value, as a fraction: 0.02 means 2%. |
sort | string: clicks | impressions | ctr | position | page | Sort column (default clicks). |
folder | string | Only 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
days | integer | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
from | string | First day, YYYY-MM-DD. Use together with "to". |
to | string | Last day, YYYY-MM-DD. |
limit | integer | Most 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
days | integer | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
from | string | First day, YYYY-MM-DD. Use together with "to". |
to | string | Last 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
days | integer | Length of each period in days (7, 14, 28, 90 or 180; default 14). |
metric | string: clicks | impressions | ctr | position | Metric to compare (default clicks). |
to | string | Last 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
type (required) | string: url | folder | query | What q is. |
q (required) | string | The URL, folder or query text (800 characters at most). |
days | integer | Period length in days (default 28). |
to | string | Last 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
days | integer | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
from | string | First day, YYYY-MM-DD. Use together with "to". |
to | string | Last 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
days | integer | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
from | string | First day, YYYY-MM-DD. Use together with "to". |
to | string | Last 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).
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
days | integer | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
from | string | First day, YYYY-MM-DD. Use together with "to". |
to | string | Last 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).
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
page (required) | string | Full 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
category | string | Only URLs in this category, for example "indexed" or "crawled_not_indexed" (see the counts in index_health). |
q | string | Only URLs that contain this text. |
page | integer | Page number, starting at 1 (default 1). |
per_page | integer | Rows 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site 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.
| Parameter | Type | Description |
|---|---|---|
site_id (in the path) | string | Site id from the sites report. Optional when the account has exactly one usable site. |
report_id (required) (in the path) | string | Report 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.
| Parameter | Type | Description |
|---|---|---|
project_id (required) (in the path) | string | Rank Tracker project id from the projects report. |
target_id | string | Country 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.
| Parameter | Type | Description |
|---|---|---|
project_id (required) (in the path) | string | Rank Tracker project id from the projects report. |
target_id | string | Country and device target inside the project. Optional. |
days | integer | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
from | string | First day, YYYY-MM-DD. Use together with "to". |
to | string | Last day, YYYY-MM-DD. |
tags | string | Comma-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.
| Parameter | Type | Description |
|---|---|---|
project_id (required) (in the path) | string | Rank 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.
| Parameter | Type | Description |
|---|---|---|
project_id (required) (in the path) | string | Rank Tracker project id from the projects report. |
target_id | string | Country and device target inside the project. Optional. |
window | integer | Days 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.
| Parameter | Type | Description |
|---|---|---|
project_id (required) (in the path) | string | Rank Tracker project id from the projects report. |
target_id | string | Country and device target inside the project. Optional. |
days | integer | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
from | string | First day, YYYY-MM-DD. Use together with "to". |
to | string | Last day, YYYY-MM-DD. |
tags | string | Comma-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.
| Parameter | Type | Description |
|---|---|---|
project_id (required) (in the path) | string | Rank Tracker project id from the projects report. |
target_id | string | Country and device target inside the project. Optional. |
keyword_id (required) (in the path) | string | Keyword id from project, project_latest or project_period. |
days | integer | Length of the period in days, ending on the last day with data (1-240, default 28). Ignored when from and to are given. |
from | string | First day, YYYY-MM-DD. Use together with "to". |
to | string | Last 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.
| Parameter | Type | Description |
|---|---|---|
project_id (required) (in the path) | string | Rank 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 address | https://app.seosignal.net/api/mcp?token=ssk_YOUR_KEY |
|---|---|
| Transport | Streamable HTTP (JSON-RPC 2.0). POST only; every reply is plain JSON; no session is kept. |
| Protocol versions | 2025-06-18, 2025-03-26, 2024-11-05 |
| Authentication | The 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.
| Tool | Product | Use it to… |
|---|---|---|
sites | Assistant or Tracker | List sites |
performance | Assistant | Site performance |
queries | Assistant | Search queries |
pages | Assistant | Pages |
countries | Assistant | Countries |
devices | Assistant | Devices |
changes | Assistant | What changed |
explore | Assistant | Explore a page, folder or query |
opportunities | Assistant | Growth opportunities |
index_health | Assistant | Index health |
traffic | Assistant | Traffic report |
segments | Assistant | Brand and search intent |
hosts | Assistant | Hosts |
page_queries | Assistant | Queries of one page |
index_urls | Assistant | Index status of URLs |
client_reports | Assistant | Client reports |
client_report | Assistant | One client report |
projects | Tracker | Rank Tracker projects |
project_latest | Tracker | Latest rank changes |
project_period | Tracker | Rank changes in a period |
project | Tracker | One project |
project_overview | Tracker | Project overview |
project_matrix | Tracker | Daily positions |
project_keyword_history | Tracker | History of one keyword |
project_members | Tracker | Project members |
tags | Tracker | Keyword 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
| Date | Version | Change |
|---|---|---|
| 16 Nov 2026 | 1 | First 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].

