SEO

get_seo_rankings

Each tracked keyword's Google position on every day it was checked over the range.

readReads only. Annotated read-only, so a client can call it without asking.

Plan: Track and above
Rate cost: 2 units
REST: GET /projects/{project_id}/seo/rankings

Try asking

“Chart our position for 'gst invoicing software' over the last three months.”

get_seo_rankings

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_seo_rankings",
    "arguments": {
      "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "range": "90d"
    }
  }
}

structuredContent

{
  "content": [
    {
      "type": "text",
      "text": "…the same JSON, as text…"
    }
  ],
  "structuredContent": {
    "range": "90d",
    "keywords": [
      {
        "keyword_id": "7a1e9b2c-3d4f-4a5b-8c6d-0e1f2a3b4c5d",
        "keyword": "gst invoicing software",
        "points": [
          {
            "date": "2026-08-30",
            "position": 6
          },
          {
            "date": "2026-09-06",
            "position": 4
          }
        ],
        "ai_overview": true
      }
    ]
  },
  "isError": false
}

Arguments

Passed as the tool call's arguments.

project_idstringrequired

The project to read, from list_projects.

rangeenum<string>default 90d

How far back to measure.

Values:7d30d90d

Result

The same object as Get rankings, returned as structured output.

rangestring

The range read.

Values:7d30d90d

keywordsobject[]

One series per keyword with a check in the range.

+Show child attributes

keyword_idstring

Keyword id.

keywordstring

The search term.

pointsobject[]

One per day the position was checked, oldest first.

+Show child attributes

datestring

Day, as YYYY-MM-DD.

positionintegernullable

Position within the top 20; null when not in it.

ai_overviewbooleannullable

Whether the latest check saw an AI Overview. Null: never checked.

Errors

404 not_found	The project or item doesn't exist in this workspace. A project from another workspace also returns 404, never 403.
422 invalid_request	A parameter or body field is missing or has the wrong type or value. The message names the field. Also returned when a write would pass the plan's prompt limit.
401 unauthorized	No key was sent, or the key is unknown, revoked or expired, or the member who created it has left the workspace or been deactivated.
402 plan_required	The workspace's plan doesn't include API access. It's included on every plan from Track up — Solo is the one without it.
403 workspace_not_approved	The workspace is still waiting for approval, or wasn't approved.
429 rate_limited	Too many requests this minute. Wait for the number of seconds in the `Retry-After` header, then retry.

Every code, and what to retry, is in Errors.

Failures arrive as a tool error — isError: true with code: message as text. See Using the tools.