Outcomes

Get AI referral traffic

Visits and conversions that arrived from AI assistants, and how closely they track your visibility.

GEThttps://api.vidrys.com/v1/projects/{project_id}/ai-referrals

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

connected is false until a traffic source is linked to the project; the totals can still hold earlier data.

curl --request GET \
  --url "https://api.vidrys.com/v1/projects/{project_id}/ai-referrals" \
  --header "Authorization: Bearer $VIDRYS_API_KEY"

200 · success

{
  "connected": true,
  "total_sessions": 1284,
  "total_conversions": 37,
  "by_platform": [
    {
      "platform_label": "ChatGPT",
      "sessions": 742,
      "conversions": 21
    },
    {
      "platform_label": "Perplexity",
      "sessions": 318,
      "conversions": 9
    }
  ],
  "series": [
    {
      "date": "2026-09-20",
      "sessions": 61,
      "conversions": 2
    }
  ],
  "visibility_correlation": 0.463
}

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.

Response · 200

application/json

connectedboolean

True when the project has a traffic source connected (analytics, server logs or an upload).

total_sessionsinteger

AI-referred visits, all time.

total_conversionsinteger

Conversions from them, all time.

by_platformobject[]

Per assistant, most visits first.

+Show child attributes

platform_labelstring

The assistant, e.g. ChatGPT.

sessionsinteger

Visits.

conversionsinteger

Conversions.

seriesobject[]

Daily totals, oldest first. Days with no traffic are left out.

+Show child attributes

datestring

Day, as YYYY-MM-DD.

sessionsinteger

Visits.

conversionsinteger

Conversions.

visibility_correlationnumber

Correlation between daily GEO score and daily AI-referred visits, −1 to 1. 0 when there aren't enough days to say.

Errors

404 not_found	The project or item doesn't exist in this workspace. A project from another workspace also returns 404, never 403.
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.