SEO

list_seo_keywords

The keywords the project tracks and the Search Console queries it is close to winning: device, source, search volume, difficulty, latest and previous Google position, and whether the results page shows an AI Overview.

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

Plan: Track and above
Rate cost: 1 unit
REST: GET /projects/{project_id}/seo/keywords

Try asking

“Which of our keywords moved up since the last check?”

list_seo_keywords

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

structuredContent

{
  "content": [
    {
      "type": "text",
      "text": "…the same JSON, as text…"
    }
  ],
  "structuredContent": {
    "keywords": [
      {
        "id": "7a1e9b2c-3d4f-4a5b-8c6d-0e1f2a3b4c5d",
        "keyword": "gst invoicing software",
        "target_url": "https://acmeinvoicing.com/pricing",
        "device": "desktop",
        "country": "in",
        "tracked": true,
        "source": "manual",
        "search_volume": 2400,
        "difficulty": 38,
        "cpc_usd": 1.2,
        "position": 4,
        "previous_position": 6,
        "ai_overview": true
      }
    ],
    "page": {
      "page": 1,
      "page_size": 50,
      "total": 1
    }
  },
  "isError": false
}

Arguments

Passed as the tool call's arguments.

project_idstringrequired

The project to read, from list_projects.

pageintegerdefault 1

Page number, from 1.

page_sizeintegerdefault 50

Rows per page, up to 100.

Result

The same object as List keywords, returned as structured output.

keywordsobject[]

Tracked keywords and Search Console opportunities, alphabetical.

+Show child attributes

idstring

Keyword id.

keywordstring

The search term.

target_urlstringnullable

The page that should rank for it; decides which result counts as the brand's.

devicestring

Which results page is checked.

Values:desktopmobile

countrystring

Two-letter country code the check is made from.

trackedboolean

Whether its position is checked on the plan's cadence. A Search Console opportunity past the plan's keyword allowance is listed but not tracked.

sourcestring

Where it came from: added by hand, found in Search Console ranking 11–20, or created for a published draft.

Values:manualgsc_opportunitycontent_pipeline

search_volumeintegernullable

Monthly searches, from keyword research — or, on a Search Console opportunity, its impressions in the latest window.

difficultynumbernullable

Ranking difficulty, 0–100, from keyword research.

cpc_usdnumbernullable

Advertisers' cost per click in US dollars, from keyword research.

positionintegernullable

Latest Google position within the top 20. Null: not in the top 20, or never checked.

previous_positionintegernullable

The position on the check before that.

ai_overviewbooleannullable

Whether the latest rank check saw an AI Overview on this keyword's results page. Null: never checked.

pageobject

Where these rows sit in the full list.

+Show child attributes

pageinteger

This page's number, from 1.

page_sizeinteger

Rows per page.

totalinteger

Rows across every page.

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.