Visibility

Get visibility overview

The command centre in one call: the five headline numbers, a row per AI engine, and the alerts raised in the window.

GEThttps://api.vidrys.com/v1/projects/{project_id}/visibility

Plan: Grow and above
Key: read
Rate cost: 1 unit
MCP tool: get_visibility_overview

Everything is pooled over the window — every prompt, run and sample. Deltas compare it with the window of the same length before it.

curl --request GET \
  --url "https://api.vidrys.com/v1/projects/{project_id}/visibility?range=7d" \
  --header "Authorization: Bearer $VIDRYS_API_KEY"

200 · success

{
  "range": "7d",
  "metrics": [
    {
      "key": "geoScore",
      "label": "GEO score",
      "value": "34",
      "caption": "out of 100 · ±4.2",
      "delta": 2.1
    },
    {
      "key": "retrievability",
      "label": "AEO score",
      "value": "71",
      "caption": "out of 100",
      "delta": null
    },
    {
      "key": "mentions",
      "label": "Mentions",
      "value": "54",
      "caption": "AI answers that mention you",
      "delta": null
    },
    {
      "key": "openGaps",
      "label": "Open gaps",
      "value": "9",
      "caption": "prompts we don't win",
      "delta": -2
    },
    {
      "key": "answersFlipped",
      "label": "Answers flipped",
      "value": "3",
      "caption": "loss→win across runs",
      "delta": null
    }
  ],
  "platforms": [
    {
      "platform_id": "chatgpt",
      "platform_label": "ChatGPT",
      "probes_won": 9,
      "total_probes": 40,
      "geo_score": 31.4,
      "visibility": 45,
      "visibility_delta": 5,
      "mention_quality": 69.8,
      "citation_rate": 12.5,
      "citation_rate_delta": -2.5,
      "win_rate": 22.5
    },
    {
      "platform_id": "perplexity",
      "platform_label": "Perplexity",
      "probes_won": 14,
      "total_probes": 40,
      "geo_score": 38.6,
      "visibility": 57.5,
      "visibility_delta": -2.5,
      "mention_quality": 67.1,
      "citation_rate": 22.5,
      "citation_rate_delta": 0,
      "win_rate": 35
    }
  ],
  "alerts": [
    {
      "message": "3 platforms not recommending you for 'best invoicing software for freelancers in India'",
      "tone": "warning",
      "platform": "chatgpt"
    }
  ]
}

Authorization

Sent as a header on every request.

Authorizationstringrequired

A Vidrys API key, sent as Bearer vidrys_sk_…. A read key is enough. See Authentication.

Path parameters

project_idstringrequired

The project's id, from List projects.

Query parameters

rangeenum<string>default 7d

How far back to measure, counted from the newest run.

Values:7d30d90d

Response · 200

application/json

rangestring

The window the numbers cover.

Values:7d30d90d

metricsobject[]

The five headline cards.

+Show child attributes

keystring

Which headline card. All five are always returned, in this order.

Values:geoScoreretrievabilitymentionsopenGapsanswersFlipped

labelstring

The card's title, e.g. GEO score.

valuestring

The number as the dashboard prints it, e.g. "42". retrievability is "—" until the site has been audited.

captionstring

The line under the number, e.g. out of 100 · ±4.2 (a 95% interval).

deltanumbernullable

Change against the previous window of the same length, in the card's unit: score points for geoScore (0 unless the change is significant), a count for openGaps (negative is good). Null on the other cards.

platformsobject[]

One row per engine, pooled over the window.

+Show child attributes

platform_idstring

Engine id. Engines your plan doesn't run are listed with zeros.

Values:chatgptperplexitygeminicopilotai_overviewsclaude

platform_labelstring

Display name, e.g. AI Overviews.

probes_woninteger

Answers that won: the brand recommended with a quality of at least 0.5.

total_probesinteger

Answers on this engine, counting every prompt, run and sample.

geo_scorenumber

GEO score, 0–100: the average answer quality across prompts, scaled to 100.

visibilitynumber

Share of answers that mention the brand at all, 0–100.

visibility_deltanumber

Change in visibility against the previous window, in percentage points. 0 with no comparable window.

mention_qualitynumbernullable

Average quality of the answers that do mention the brand, 0–100. Null until at least 8 prompts have a mention.

citation_ratenumber

Share of answers that cite one of the brand's own domains, 0–100.

citation_rate_deltanumber

Change in citation_rate, in percentage points.

win_ratenumber

probes_won as a share of total_probes, 0–100.

alertsobject[]

Alerts raised in the window. At most 8.

+Show child attributes

messagestring

The alert, as the dashboard shows it.

tonestringnullable

Severity.

Values:warning

platformstringnullable

The engine it concerns. Null for site-audit alerts.

Values:chatgptperplexitygeminicopilotai_overviewsclaude

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.