SEO

Get organic traffic

Daily clicks and impressions from Search Console over the range, and the latest finalised week's top queries and top pages by clicks.

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

Plan: Track and above
Key: read
Rate cost: 1 unit
MCP tool: get_seo_traffic

Get organic traffic

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

200 · success

{
  "connected": true,
  "awaiting_data": false,
  "trend": [
    {
      "date": "2026-09-01",
      "clicks": 58,
      "impressions": 3100,
      "avg_position": 14.9
    }
  ],
  "top_queries": [
    {
      "term": "gst invoicing software",
      "clicks": 210,
      "impressions": 4100,
      "ctr": 5.12,
      "position": 4.2
    },
    {
      "term": "invoice app for freelancers",
      "clicks": 96,
      "impressions": 5300,
      "ctr": 1.81,
      "position": 8.7
    }
  ],
  "top_pages": [
    {
      "term": "https://acmeinvoicing.com/pricing",
      "clicks": 340,
      "impressions": 6200,
      "ctr": 5.48,
      "position": 5.1
    }
  ]
}

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 30d

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

Values:7d30d90d

Response · 200

application/json

connectedboolean

Whether Search Console is connected.

awaiting_databoolean

Connected, but nothing synced for the range yet.

trendobject[]

One point per day in the range, oldest first.

+Show child attributes

datestring

Day, as YYYY-MM-DD.

clicksinteger

Clicks from Google search that day, from Search Console.

impressionsinteger

Times the site appeared in results that day.

avg_positionnumbernullable

Average position across the day's impressions. Null when Search Console reported none.

top_queriesobject[]

The latest finalised week's top queries by clicks, up to 25.

+Show child attributes

termstring

The query, or the page URL.

clicksinteger

Clicks over the window.

impressionsinteger

Impressions over the window.

ctrnumber

Click-through rate, 0–100.

positionnumbernullable

Average position over the window.

top_pagesobject[]

The same week's top pages by clicks, up to 25.

+Show child attributes

termstring

The query, or the page URL.

clicksinteger

Clicks over the window.

impressionsinteger

Impressions over the window.

ctrnumber

Click-through rate, 0–100.

positionnumbernullable

Average position over the window.

Errors

403 plan_feature_unavailable	The feature is on a higher plan. Bulk exports and webhooks are Custom-only.
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.