Gaps & citations

list_gaps

Questions the brand is losing: on which engines, to whom, the answer order, and the trend.

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

Plan: Grow and above
Rate cost: 2 units
REST: GET /projects/{project_id}/gaps

Try asking

“What are our biggest gaps right now, and what should we publish?”

list_gaps

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

structuredContent

{
  "content": [
    {
      "type": "text",
      "text": "…the same JSON, as text…"
    }
  ],
  "structuredContent": {
    "gaps": [
      {
        "prompt_id": "0e9a7c55-2b3d-4c1e-8f6a-9d0b1c2e3f4a",
        "prompt_ref": 12,
        "prompt_text": "best invoicing software for freelancers in India",
        "platforms_losing": [
          "chatgpt",
          "gemini",
          "perplexity"
        ],
        "platforms_winning": [
          "ai_overviews"
        ],
        "top_competitor": "Northwind Billing",
        "suggested_content_type": "comparison",
        "impact": "high",
        "reasoning_card_ids": [
          "a3c9e1f0-4b2d-4e8a-9f1c-7d6b5a4e3c2b"
        ],
        "win_rate_history": [
          {
            "date": "2026-09-18",
            "win_rate": 50,
            "probes": 4
          },
          {
            "date": "2026-09-20",
            "win_rate": 25,
            "probes": 4
          }
        ],
        "trend": "worsening",
        "open_runs": 2,
        "answer_order": [
          {
            "name": "Northwind Billing",
            "is_brand": false
          },
          {
            "name": "Acme Invoicing",
            "is_brand": true
          },
          {
            "name": "Contoso Books",
            "is_brand": false
          }
        ],
        "answers_total": 4,
        "rival_appearances": 4,
        "your_appearances": 2
      }
    ],
    "page": {
      "page": 1,
      "page_size": 50,
      "total": 9
    }
  },
  "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 gaps, returned as structured output.

gapsobject[]

Prompts being lost, highest impact first.

+Show child attributes

prompt_idstring

The prompt being lost.

prompt_refinteger

The prompt's short number.

prompt_textstring

The prompt.

platforms_losingstring[]

Engine ids losing it in the latest run.

platforms_winningstring[]

Engine ids winning it.

top_competitorstring

The competitor most often winning where the brand is absent. Empty string when none.

suggested_content_typestring

The kind of page likely to win it back, from the prompt's wording.

Values:comparisonpricingfaqdefinitiondocumentationintegrationhow-touse-caseproductcase-studytrust-signalsresearch

impactstring

high when 3 or more engines lose it, medium for 2, low for 1.

Values:highmediumlow

reasoning_card_idsstring[]

“Why?” cards for the losing engines. Each matches a result's reasoning_card_id.

win_rate_historyobject[]

The last 8 days with answers.

+Show child attributes

datestring

Day, as YYYY-MM-DD.

win_rateinteger

Share of that day's answers won, 0–100, rounded.

probesinteger

Answers that day, all engines.

trendstring

The latest day's win rate against the day before.

Values:newimprovingworseningflat

open_runsinteger

Consecutive recent days with at least one lost answer.

answer_orderobject[]

Who the answers name, in order of first mention. Up to 6.

+Show child attributes

namestring

Brand or competitor.

is_brandboolean

True for your brand.

answers_totalinteger

Latest-run answers for the prompt.

rival_appearancesinteger

Of those, answers naming top_competitor.

your_appearancesinteger

Of those, answers naming your brand at all.

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 Grow, Scale and Custom.
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.