[ CH_05.01 / REST_API ]
Endpoints and authentication
All endpoints live under /api/v1. Two auth modes: interactive/management endpoints use a session JWT (Authorization: Bearer <jwt>) from magic-link login, while the read-only Analytics API (/projects/{id}/analytics/*) and the agent recommendations feed authenticate with a per-project API key sent as the x-api-key header — generate one under your project's Settings → Developer & API → Agent API Key. Analytics calls are metered per project and return X-RateLimit-* headers.
To create and manage projects programmatically, use an account API key (vsak_) with the Provisioning API — it spans every project you own and carries explicit write scopes. The per-project vsk_ key stays read-only and is minted from a project that already exists, so it can neither create one nor reach a second.
> base_url
https://api.vectraseo.com/api/v1 This reference is generated from the API's own route table, so it lists every customer route (224 of them). Scope says what a caller needs:
- A scope name such as
projects:read: a signed-in session, or an account key (vsak_) that holds that scope. Two names joined by + means the key needs both. - project key: the
x-api-key header only, with the project's vsk_ key or an account key that holds projects:read. A session is not accepted. - session: a signed-in session only. No API key can call it.
- none: no authentication.
Plan shows paid when the route returns 403 with code: "subscription_limit" on a free account. paid* means only some requests are paid, as the description says. Plan quotas, such as the monthly post allowance, also apply and are not shown here.
Authentication
POST/auth/magic-linknone · — Request magic link
POST/auth/magic-link/verifynone · — Verify token, get JWT
POST/auth/logoutnone · — Clear the session cookie
GET/auth/mesession · — The signed-in user, with admin, partner and billing status
PATCH/auth/preferencessession · — Save UI preferences on your user
POST/auth/lookupnone · — Return whether an email has a registered passkey.
POST/auth/passkey/register/beginsession · — Start registering a passkey (WebAuthn options)
POST/auth/passkey/register/completesession · — Finish registering a passkey
POST/auth/passkey/authenticate/beginnone · — Start a passkey sign-in (WebAuthn challenge)
POST/auth/passkey/authenticate/completenone · — Finish a passkey sign-in
GET/auth/passkeyssession · — List your passkeys
PATCH/auth/passkeys/:credential_idsession · — Rename a passkey
DELETE/auth/passkeys/:credential_idsession · — Delete a passkey
API keys
GET/account/api-keys/scopesnone · — Every account-key scope and what it grants
GET/account/api-keyssession · — Your account keys (metadata only, never the key)
POST/account/api-keyssession · — Create a vsak_ account key with chosen scopes. The key is returned once
DELETE/account/api-keys/:key_idsession · — Revoke an account key, effective immediately
GET/projects/:id/api-keysession · — The project key's prefix and dates, never the key
POST/projects/:id/api-key/rotatesession · — Issue a new vsk_ project key, returned once. The old key stops working
POST/projects/:id/api-key/revokesession · — Revoke the project key. Later calls get 401
Provisioning API (account key)
GET/account/meprojects:read · — Identify the calling key: account, plan, project count
GET/account/projectsprojects:read · — Every project on the account
GET/account/portfolioprojects:read · paid — One overview per project for triage; drill-downs stay per-project · fixed windows · paid plans
POST/onboarding/audit/:audit_idsession · — Turn a completed free audit into a project with a site-health monitor
POST/onboardingprojects:write · — Create AND configure a project in one call → 202 {project_id, job_id}
GET/onboarding/:job_idprojects:read · — Poll an onboarding run: per-step outcomes + the project as it stands
Projects
GET/projectsprojects:read · — List projects
POST/projectsprojects:write · — Create project
GET/projects/dashboard-summarysession · — Post and competitor counts per project, for the dashboard
GET/projects/list-summarysession · — Per-project card data for the projects list
GET/projects/:idprojects:read · — Get project
PUT/projects/:idprojects:write · — Update project
POST/projects/:id/url-notices/ackprojects:write · — Hide the "we fixed a typo in your URL" notice for one field.
DELETE/projects/:idsession · — Delete project
GET/projects/:id/summaryprojects:read · — Schedule and post count for one project
POST/projects/:id/runjobs:write · paid — Trigger pipeline run: competitor analysis, gaps, posts → 202 {job_id}
GET/projects/:id/generation-configprojects:read · — Read the project's intent-weighted topic-generation policy.
PUT/projects/:id/generation-configprojects:write · — Replace the generation policy. Then call /gaps/rescore to re-rank existing gaps
POST/projects/:id/credentials/revealsession · — Reveal one stored CMS credential
GET/projects/:id/indexnowprojects:read · — The project's IndexNow key, where to host it, and the last check.
POST/projects/:id/indexnow/checkprojects:write · — Mint the key if needed and check the key file on the project's host now.
Competitors
GET/projects/:id/competitorsprojects:read · — List competitors
GET/projects/:id/competitors/discoverprojects:read · — Suggest competitors from DataForSEO
POST/projects/:id/competitorsprojects:write · — Add competitor
DELETE/projects/:id/competitors/:cidprojects:write · — Remove competitor
POST/projects/:id/competitors/analyzejobs:write · paid — Run analysis (starts the same full content run as /run) → 202 {job_id}
Content Gaps
GET/projects/:id/gapsprojects:read · — List gaps (paginated: ?limit, ?cursor)
POST/projects/:id/gaps/identifyjobs:write · paid — Identify gaps → 202 {job_id}
POST/projects/:id/gaps/rescoreprojects:write · — Re-rank existing gaps after a generation-config change. No new gaps, no model call
POST/projects/:id/gaps/:gap_id/rejectprojects:write · — Mark a topic off-target. Kept as a negative example for later gap identification
DELETE/projects/:id/gaps/:gap_idgaps:delete · — Delete gap
Blog Posts
GET/projects/:id/postsprojects:read · — List posts (paginated: ?limit, ?cursor)
POST/projects/:id/posts/generatejobs:write · — Generate posts → 202 {job_id}
POST/projects/:id/posts/bulk-delete-archivedsession · — Permanently delete up to 20 archived posts, preserving request order.
POST/projects/:id/images/presignsession · — Get a presigned URL to upload an image
POST/projects/:id/posts/hybrid-generatejobs:write · — Generate a post from your own outline, with an optional image
POST/projects/:id/posts/title-recommendationssession · paid — Recommend SEO/conversion titles and focus keywords for outline-based posts.
GET/projects/:id/posts/:post_idprojects:read · — Get post
GET/projects/:id/posts/:post_id/index-stateprojects:read · — Cached Google URL Inspection state for the post's live URL
POST/projects/:id/posts/:post_id/recheck-indexsession · — Re-run URL Inspection for the post's live URL
GET/projects/:id/posts/:post_id/gscprojects:read · — Search Console metrics for one post
GET/projects/:id/posts/:post_id/bodyprojects:read · — The post's HTML body
PUT/projects/:id/posts/:post_idprojects:write · — Update post
POST/projects/:id/posts/:post_id/repair-metadatasession · paid — AI repair of the post's SEO title and meta description
DELETE/projects/:id/posts/:post_idsession · — Delete post
POST/projects/:id/posts/:post_id/publishcontent:publish · — Publish to CMS
GET/projects/:id/posts/:post_id/exportsession · — Export a post as an HTML or Markdown file download.
POST/projects/:id/posts/:post_id/regenerate-imagessession · paid — Regenerate the post's images → 202 {job_id}
POST/projects/:id/posts/:post_id/repair-contentjobs:write · paid — Run Auto-fix on the post's content (queued job)
POST/projects/:id/posts/:post_id/regenerate-contentjobs:write · paid — Rewrite the post without the product claims its destination rejected, then re-check it
POST/projects/:id/posts/:post_id/advance-phasesession · paid — Run the next publish-readiness step on the post
POST/projects/:id/posts/:post_id/replaysession · paid — Send an archived post back through publish readiness
POST/projects/:id/posts/:post_id/remove-unconfirmed-claimssession · paid — Remove unconfirmed claims from a held draft and re-check it
POST/projects/:id/posts/:post_id/supersedesession · — Mark a published post as consolidated into another published post.
DELETE/projects/:id/posts/:post_id/supersedesession · — Clear the superseded mark; the post is written to and checked again.
POST/projects/:id/posts/:post_id/archivesession · — Archive a post. Archived posts are purged after five days
POST/projects/:id/posts/:post_id/unarchivesession · — Restore an archived post.
POST/projects/:id/posts/:post_id/retry-truthsession · paid — Re-run the claim check on the post
Scheduler
GET/projects/:id/scheduleprojects:read · — Get schedule
PUT/projects/:id/scheduleprojects:write · — Update schedule
DELETE/projects/:id/scheduleprojects:write · — Disable schedule
Sitemap
POST/projects/:id/sitemapjobs:write · — Fetch the project's sitemap → 202 {job_id}
GET/projects/:id/sitemapprojects:read · — Stored sitemap data
DELETE/projects/:id/sitemapsession · — Clear stored sitemap data
Monitors
GET/projects/:id/monitorsprojects:read · — List monitors
GET/projects/:id/monitors/summaryprojects:read · — Site-monitor rollup for the project
POST/projects/:id/monitorsprojects:write · — Create monitor
GET/projects/:id/monitors/:midprojects:read · — Get monitor
PATCH/projects/:id/monitors/:midprojects:write · — Update monitor (partial)
DELETE/projects/:id/monitors/:midsession · — Delete monitor
POST/projects/:id/monitors/:mid/scanjobs:write · — Trigger manual scan
POST/projects/:id/monitors/:mid/refresh-sitemapjobs:write · — Re-fetch the monitor's sitemap (queued job)
GET/projects/:id/monitors/:mid/scansprojects:read · — List scan history
GET/projects/:id/monitors/:mid/scans/:sid/issuesprojects:read · — A scan's issues — bare JSON array; next page via the X-Next-Cursor header (?cursor=)
POST/projects/:id/monitors/:mid/issues/implementjobs:write · paid* — Fix one issue on a page VectraSEO published → 202. Model fixers need a paid plan; deterministic ones are free
POST/projects/:id/monitors/:mid/issues/implement-batchjobs:write · paid* — Fix every VectraSEO-published page one rule flagged in a scan. Model fixers need a paid plan
POST/projects/:id/monitors/:mid/issues/change-setjobs:write · paid* — Build a reviewable change-set for a page VectraSEO cannot republish → 202 {job_id}. Model fixers need a paid plan
GET/projects/:id/change-setsprojects:read · — The project's stored change-sets
GET/projects/:id/change-sets/job/:job_idprojects:read · — The change-set a finished change-set job built
POST/projects/:id/monitors/:mid/remediation/snapshotssession · — Record that you copied or downloaded a scan's fix plan
GET/projects/:id/monitors/:mid/remediation/snapshotssession · — Fix-plan export history, newest first
GET/projects/:id/monitors/:mid/remediationsession · — Status of each finding in the current fix plan, plus verified fixes
GET/projects/:id/visibility/monitorsprojects:read · — List AI visibility monitors
GET/projects/:id/visibility/summaryprojects:read · — Per-project rollup
POST/projects/:id/visibility/monitorsprojects:write · paid — Create AI visibility monitor
GET/projects/:id/visibility/monitors/:midprojects:read · — Get monitor (with prompts)
GET/projects/:id/visibility/monitors/:mid/remediationprojects:read · — Remediation plan from the latest completed scan
PATCH/projects/:id/visibility/monitors/:midprojects:write · — Update monitor — assistants, prompts, schedule, alerts
DELETE/projects/:id/visibility/monitors/:midprojects:write · — Delete monitor
POST/projects/:id/visibility/monitors/:mid/scanjobs:write · paid — Trigger manual citation scan
GET/projects/:id/visibility/monitors/:mid/scansprojects:read · — List scan history
GET/projects/:id/visibility/monitors/:mid/scans/:sid/resultsprojects:read · — Get scan results per assistant
GET/capabilities/visibility-assistantsnone · — Which AI assistants visibility scans can query
GET/projects/:id/ranksprojects:read · — List tracked keywords + current rank + 30-day history
GET/projects/:id/ranks/keywordsprojects:read · — List tracked keywords
POST/projects/:id/ranks/keywordsprojects:write · — Add a tracked keyword
DELETE/projects/:id/ranks/keywords/:keywordprojects:write · — Remove a tracked keyword
GET/projects/:id/ranks/summaryprojects:read · — Top wins this week + drop alerts rollup
GET/projects/:id/ranks/suggestionsprojects:read · — Auto-suggest keywords from project + GSC
POST/projects/:id/ranks/fetchjobs:write · — Force a rank refresh for the project
Google Search Console
GET/projects/:id/gsc/statussession · — Search Console connection status
GET/projects/:id/gsc/summarysession · — Project-level clicks and impressions
GET/projects/:id/gsc/pagessession · — Search Console data for sitemap pages that are not posts
POST/projects/:id/gsc/authorizesession · — Start OAuth — returns Google consent URL
POST/projects/:id/gsc/propertiessession · — Exchange the OAuth code and list your Search Console properties
POST/projects/:id/gsc/connectsession · — Bind a Search Console property to the project
DELETE/projects/:id/gsc/connectsession · — Disconnect Search Console (stored metrics are kept)
POST/projects/:id/gsc/refreshsession · — Force a Search Console refresh (queued job)
POST/projects/:id/gsc/sitemapsession · — Submit this project's sitemap to Google now.
GET/projects/:id/search/overviewprojects:read · — Clicks, impressions, CTR, position + daily series for an explicit 28-day window (window_start/window_end)
GET/projects/:id/search/queriesprojects:read · — Top queries
GET/projects/:id/search/pagesprojects:read · — Top pages
GET/projects/:id/search/pages/trendsprojects:read · — Per-page momentum — which pages are improving vs slipping over time.
GET/projects/:id/search/pages/historyprojects:read · — Weekly series for one page, with its current trend
GET/projects/:id/search/index-coverageprojects:read · — Page indexing buckets from URL Inspection API
GET/projects/:id/indexing-healthprojects:read · — Discovery-health findings for the project's published posts.
GET/projects/:id/search/index-coverage/issuesprojects:read · — FAIL-bucket URLs with example fixes
GET/projects/:id/search/index-coverage/urlsprojects:read · — Inspected URLs, filterable and cursor-paginated
POST/projects/:id/search/index-coverage/inspect-urljobs:write · — Re-run URL Inspection on one URL now ("Validate fix")
Google Indexing API
GET/projects/:id/indexing-api/statusprojects:read · — Connection state (never returns the secret)
PUT/projects/:id/indexing-api/credentialssession · — Save your own Google OAuth client and record your risk consent
POST/projects/:id/indexing-api/authorizesession · — Start OAuth with your own client — returns the consent URL
POST/projects/:id/indexing-api/connectsession · — Exchange the OAuth code and turn on notifications
PUT/projects/:id/indexing-api/enabledprojects:write · — Pause or resume notifications, keeping the connection
DELETE/projects/:id/indexing-apisession · — Remove the credentials and the connection
POST/projects/:id/indexing-api/request-indexingjobs:write · — Submit selected URLs to the Google Indexing API (URL_UPDATED)
POST/projects/:id/indexing-api/request-all-not-indexedjobs:write · — Submit every not-indexed page in one action
GA4
GET/projects/:id/ga4/statussession · — Connection status + bound property
POST/projects/:id/ga4/authorizesession · — Start OAuth — returns Google consent URL
POST/projects/:id/ga4/propertiessession · — List connectable GA4 properties for the account
POST/projects/:id/ga4/connectsession · — Bind a GA4 property to the project
DELETE/projects/:id/ga4/connectsession · — Disconnect GA4
POST/projects/:id/ga4/refreshsession · — Force a GA4 metrics refresh
GET/projects/:id/ga4/pagessession · — GA4 top pages + next-best-actions
First-party traffic (push your own logs)
POST/projects/:id/traffic/dailytraffic:write · paid — Push one UTC day of per-page aggregates. A replay replaces that day
GET/projects/:id/traffic/overviewprojects:read · — 28-day totals vs the previous 28, daily series, top referrers, AI crawlers, countries, UTM
GET/projects/:id/traffic/pagesprojects:read · — Per-page human visits, crawler fetches by class, AI-assistant referrals
Recommendations
GET/projects/:id/recommendationsrecommendations:read · — List active recommendations across monitors
GET/projects/:id/recommendations/:rule_id/:target_kind/:target_idjobs:write + recommendations:read · paid — Per-rule detail (cache-or-generate)
POST/projects/:id/recommendations/:rule_id/:target_kind/:target_id/regeneratejobs:write + recommendations:read · paid — Force a fresh AI generation
POST/projects/:id/recommendations/:rule_id/:target_kind/:target_id/optimizedprojects:write + recommendations:read · — Dismiss until its Search Console numbers change
POST/projects/:id/recommendations/:rule_id/:target_kind/:target_id/applycontent:publish + recommendations:read · — Apply the suggested fix (republishes the post)
POST/projects/:id/recommendations/apply-allcontent:publish + recommendations:read · — Apply every applicable fix in one job. Send dry_run: true first to preview
GET/projects/:id/agent/recommendationsproject key · — Agent-consumable feed (GSC index FAIL buckets, monitor issues, AEO gaps) — see below
Analytics API (x-api-key · read-only · paid plans)
GET/projects/:id/analytics/overviewproject key · paid — One-call snapshot: health (AEO score nested), visibility, search, traffic, ranks; fixed console windows (`period_days` is echoed, not applied; `search` names its own window dates)
GET/projects/:id/analytics/search/overviewproject key · paid — GSC clicks, impressions, CTR, position + daily series for an explicit 28-day window (window_start/window_end, previous_window_*)
GET/projects/:id/analytics/search/queriesproject key · paid — Top search queries (?limit)
GET/projects/:id/analytics/search/pagesproject key · paid — Per-URL performance (?sort, ?limit)
GET/projects/:id/analytics/search/index-coverageproject key · paid — Google index buckets + sparklines
GET/projects/:id/analytics/traffic/pagesproject key · paid — GA4 per-page sessions, revenue, AI referrals
GET/projects/:id/analytics/traffic/first-partyproject key · paid — Traffic you push via /traffic/daily: 28-day per-page visits (?sort=human|human_delta|ai_crawler, ?limit)
GET/projects/:id/analytics/visibility/summaryproject key · paid — Per-monitor AI Visibility rollup (score/citation rate/SoV under latest_scan)
GET/projects/:id/analytics/visibility/monitors/:mid/scansproject key · paid — AI Visibility scan history, newest first — bare array (?limit)
GET/projects/:id/analytics/visibility/monitors/:mid/scans/:sid/resultsproject key · paid — Per-prompt, per-assistant results
GET/projects/:id/analytics/health/summaryproject key · paid — Site-health + AEO score, issue counts
GET/projects/:id/analytics/health/monitors/:mid/scansproject key · paid — Site-health scan history, newest first — { items, count } (?limit)
GET/projects/:id/analytics/health/monitors/:mid/scans/:sid/issuesproject key · paid — Issues for a scan (severity, category, fix)
GET/projects/:id/analytics/ranksproject key · paid — Tracked keywords + position history (?days)
Verification Receipt (public)
GET/verification/:project_id/:post_idnone · — Public sanitized truth report for a published post. No auth — gated to status=published.
Automation Status
GET/projects/:id/automationsession · — Read-only rollup of generation, publish, monitor, and rank automation tracks
Jobs
GET/jobs/:job_idprojects:read · — Poll job status
POST/jobs/:job_id/canceljobs:write · — Request cancellation of a queued or running job
GET/jobs/:project_id/jobsprojects:read · — List a project's jobs
Billing
POST/billing/checkoutsession · — Start a Stripe Checkout session, or switch plan if already subscribed
POST/billing/switchsession · — Switch an existing subscription to a different plan.
POST/billing/portalsession · — Open the Stripe customer portal
GET/billing/subscriptionsession · — Get current user's subscription status for a product (content|local).
GET/billing/plansession · — Your plan limits, per product
POST/billing/cancelsession · — Cancel subscription at period end.
POST/billing/resumesession · — Undo a pending cancellation.
GET/billing/local-scout/refund-eligibilitysession · — Whether the user's Local Scout subscription is within the money-back window.
POST/billing/local-scout/refundsession · — Honor the Local Scout 30-day money-back guarantee: refund the latest payment and cancel the subscription immediately.
POST/billing/verify-sessionsession · — Verify a completed checkout session and sync subscription.
GET/billing/confignone · — Stripe publishable key
Free tools and public endpoints
POST/contactnone · — Send a message to VectraSEO
POST/auditnone · — Start a free site audit → 202 {audit_id}
GET/audit/:audit_idnone · — Poll a free audit
POST/audit/:audit_id/emailnone · — Submit an email to unlock the full audit report
GET/audit/:audit_id/og.pngnone · — Per-scan Open Graph share image.
GET/public/stats/smb-seonone · — Latest aggregate small-business SEO statistics
GET/public/stats/partner-countnone · — Number of approved partners
POST/public-tools/ai-visibilitynone · — Run the AEO readiness checks on one public URL
POST/public-tools/ai-visibility-livesession · paid — Queue a live AI-assistant visibility scan
GET/public-tools/ai-visibility-live/:sidnone · — Poll a live visibility scan
POST/public-tools/local-scoutsession · paid — Queue a Local Scout scan (needs a Local Scout plan)
GET/public-tools/local-scout/scans/:sidsession · — Poll a Local Scout scan
POST/public-tools/local-scout/previewnone · — Instant local-findability snapshot
POST/public-tools/local-scout/unlocknone · — Submit an email to see the full Local Scout fix list
GET/public-tools/local-scout/unsubscribenone · — Unsubscribe from Local Scout follow-up emails
POST/public-tools/robots-testnone · — Test robots.txt rules, fetched from a URL or pasted
POST/public-tools/meta-descriptionsession · paid — Generate meta description options
POST/public-tools/title-tagsession · paid — Generate title tag options
Partner program
POST/affiliates/applynone · — Apply to the partner program
POST/affiliates/validate-refnone · — Check whether a referral code belongs to an approved partner
POST/affiliates/track-clicknone · — Record a click on a partner link
GET/affiliates/programnone · — Program terms: commission rate, window, eligible plans
GET/affiliates/applications/:application_idnone · — Read back a submitted application
GET/affiliates/mesession · — Your partner profile
GET/affiliates/dashboardsession · — Partner dashboard totals
GET/affiliates/commissionssession · — Your commission ledger (paginated)
GET/affiliates/referralssession · — Customers you referred (paginated)
GET/affiliates/clicks/dailysession · — Daily click counts
PATCH/affiliates/settingssession · — Update your partner settings
GET/affiliates/assetssession · — Marketing assets with your referral link filled in
Agent recommendations feed
GET /projects/:id/agent/recommendations returns every current recommendation for a project in one call: Search Console findings (including Page Indexing failures), site-health SEO issues and AEO issues. It takes a project key, works on every plan, and is read-only.
severity_min
Lowest severity to include: critical, warning, info, opportunity or positive. Default positive, which keeps everything.
categories
Comma-separated subset of gsc, seo, aeo. Default all three.
limit_per_rule
Cap on items per rule, 0–500. Default 0, which means no cap.
format
json (default) or markdown.
With format=markdown the response is text/markdown: the same items written as a briefing you can paste into a coding agent such as Claude Code or Cursor. To have Claude Code fetch it and act on it:
claude-code.sh
claude "Pull SEO recommendations from
https://api.vectraseo.com/api/v1/projects/$PROJECT_ID/agent/recommendations?format=markdown
using header x-api-key: <your-key>, then group fixes by rule_id
and open a PR."
For Cursor or any other agent, fetch the briefing and paste it into the chat:
fetch-briefing.sh
curl -H "x-api-key: <your-key>" \
"https://api.vectraseo.com/api/v1/projects/$PROJECT_ID/agent/recommendations?format=markdown&severity_min=warning"
Each JSON item has a stable id, so you can compare runs to see what is new and what is resolved. A missing, revoked or wrong key returns 401 invalid_api_key; a query value outside the allowed set returns 422.
Rate limits
There is one hourly limit, and it is the same on every plan: 1,000 requests per hour (the analytics_api_rate_limit_per_hour setting). It is counted in two buckets:
- Per project for routes whose scope is project key (the Analytics API and the agent feed), whichever key you send.
- Per account for an account key (
vsak_) on every other key-reachable route.
Metered responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit the API returns 429 with Retry-After: 3600. Calls made with a signed-in session are not counted.
Analytics API · response shapes
Each /analytics/* response below is the exact shape the live API returns. Three conventions trip up first-time integrators:
- AEO readiness lives inside
health. The overview reports it as health.aeo_score — there is no top-level aeo object. - Surfaces can be
null. In /overview, each of health, visibility, search, traffic, and ranks is null until that source is connected and has data — normalize defensively. - Only scan issues are cursor-paginated.
/analytics/health/monitors/:mid/scans/:sid/issues returns { items, count, next_cursor } — follow next_cursor until it is null. Every other list endpoint returns { items, count } in one response (visibility scans and visibility results return a bare array), with no next_cursor/total. None has server-side severity/category filters. - Get a
scan_id from the scan lists./analytics/health/monitors/:mid/scans and /analytics/visibility/monitors/:mid/scans list a monitor's scans newest first (?limit 1–100, default 20). Each scan carries the scan_id the issues and results routes take; /analytics/health/summary and /analytics/visibility/summary give the monitor ids.
GET/projects/:id/analytics/overviewoverview.json
One-call snapshot. AEO is health.aeo_score (no top-level aeo). Every surface is null until its source is connected.
{
"project_id": "prj_8fa21c",
"period_days": 28,
"health": { "health_score": 92, "aeo_score": 78, "urls_checked": 184,
"critical": 0, "warning": 3, "info": 9 },
"visibility": { "visibility_score": 61, "citation_rate": 0.34, "share_of_voice": 0.22 },
"search": { "period_days": 28,
"window_start": "2026-05-01", "window_end": "2026-05-28",
"days_reported": 28,
"clicks": 12431, "clicks_prev": 11705, "impressions": 402118,
"ctr": 0.031, "position": 14.2 },
"traffic": { "sessions": 18904, "engaged_sessions": 12880,
"key_events": 311, "revenue": 4820.50, "ai_referrals": 842 },
"ranks": { "tracked": 48, "top_10": 12, "wins_this_week": 3 },
"generated_at": "2026-05-29T14:02:11Z"
}GET/projects/:id/analytics/search/overviewsearch-overview.json
GSC clicks, impressions, CTR, position for an explicit 28-day window. window_start/window_end and previous_window_start/previous_window_end name the dates; daily holds only reported days in the current window and days_reported counts them. connected is false until Search Console is linked.
{
"connected": true,
"property_url": "https://acme.com/",
"period_days": 28,
"window_start": "2026-05-01", "window_end": "2026-05-28",
"previous_window_start": "2026-04-03", "previous_window_end": "2026-04-30",
"days_reported": 28, "previous_days_reported": 28,
"clicks": 12431, "impressions": 402118, "ctr": 0.031, "position": 14.2,
"clicks_prev": 11705, "impressions_prev": 389220, "ctr_prev": 0.030, "position_prev": 15.1,
"daily": [
{ "date": "2026-05-01", "clicks": 402, "impressions": 13200, "ctr": 0.030, "position": 14.8 }
]
}GET/projects/:id/analytics/search/queriessearch-queries.json
Top queries for the most recent refresh. Capped by ?limit (default 25, max 100). Not cursor-paginated.
{
"items": [
{ "query": "ai seo audit tool", "clicks": 312, "impressions": 8400, "ctr": 0.037, "position": 6.1 }
],
"count": 25
}GET/projects/:id/analytics/search/pagessearch-pages.json
Per-URL performance with previous-period values and deltas. ?sort = clicks | clicks_delta | clicks_loss | position_delta | position_loss; ?limit max 200.
{
"items": [
{
"kind": "post", "target_id": "post_4f2a",
"url": "https://acme.com/blog/aeo-guide", "title": "The AEO Guide",
"clicks": 312, "impressions": 8400, "ctr": 0.037, "position": 6.1,
"clicks_prev": 280, "impressions_prev": 8010, "ctr_prev": 0.035, "position_prev": 7.2,
"clicks_delta": 32, "position_delta": 1.1
}
],
"count": 50
}GET/projects/:id/analytics/search/index-coverageindex-coverage.json
Google index buckets + 30-day sparklines. severity is info | warning | critical | neutral — only indexed (live on Google) is info.
{
"connected": true,
"property_url": "https://acme.com/",
"buckets": [
{ "bucket": "indexed", "severity": "info", "count": 184, "sparkline": [180,181,184], "examples": [] },
{ "bucket": "crawled_not_indexed", "severity": "warning", "count": 12, "sparkline": [10,11,12], "examples": [] },
{ "bucket": "excluded_noindex", "severity": "warning", "count": 31, "sparkline": [31,31,31], "examples": [] }
],
"total_inspected": 227,
"rollup_days": 30,
"quota": { "used_today": 14, "daily_cap": 2000 },
"last_synced_at": "2026-05-29T06:00:00Z"
}GET/projects/:id/analytics/traffic/pagestraffic-pages.json
Per-page GA4 metrics with previous-period values + ai_referrals (ChatGPT / Claude / Gemini). Returns { items, count } — not cursor-paginated.
{
"items": [
{
"target_id": "post_4f2a",
"url": "https://acme.com/blog/aeo-guide", "path": "/blog/aeo-guide",
"matched": true,
"sessions": 2104, "engaged_sessions": 1502, "engagement_rate": 0.714,
"key_events": 41, "revenue": 980.00,
"sessions_prev": 1788, "engaged_sessions_prev": 1290, "engagement_rate_prev": 0.702,
"key_events_prev": 33, "revenue_prev": 740.00,
"ai_referrals": 156, "ai_referrals_prev": 92,
"source_counts": { "google": 1402, "chatgpt.com": 98, "claude.ai": 41 }
}
],
"count": 37
}GET/projects/:id/analytics/visibility/summaryvisibility-summary.json
Per-monitor AI Visibility rollup. Headline metrics live under each monitor latest_scan; best_score/worst_score summarise across monitors. No top-level score, no by_assistant.
{
"has_monitor": true,
"best_score": 61,
"worst_score": 54,
"monitors": [
{
"monitor_id": "vis_2a91", "name": "Brand prompts", "enabled": true,
"schedule": "weekly", "assistants": ["chatgpt", "claude", "gemini"],
"last_scan_at": "2026-05-27T09:00:00Z", "next_scan_at": "2026-06-03T09:00:00Z",
"latest_scan": {
"scan_id": "vscan_88c1", "visibility_score": 61,
"citation_rate": 0.34, "share_of_voice": 0.22, "accuracy_flags": 2
}
}
]
}GET/projects/:id/analytics/visibility/monitors/:mid/scans/:sid/resultsvisibility-results.json
Per-prompt, per-assistant results. Returns a plain JSON array (no items envelope). response_accurate is reserved and currently always null.
[
{
"scan_id": "vscan_88c1", "created_at": "2026-05-27T09:01:12Z",
"assistant": "chatgpt", "prompt_id": "pr_01",
"prompt_text": "best ai seo tools 2026",
"answer_text": "…",
"cited": true, "text_cited": true, "domain_cited": true,
"position": 2, "matched_alias": "VectraSEO",
"matched_source": { "url": "https://acme.com/blog/aeo-guide" },
"sources": ["https://acme.com/blog/aeo-guide"],
"competitors_cited": ["arvow.com"], "response_accurate": null,
"model": "gpt-…", "cost_usd": 0.0021, "error": null
}
]GET/projects/:id/analytics/health/summaryhealth-summary.json
Per-monitor site-health rollup. health_score, aeo_score, and issue counts live under each monitor latest_scan. No monitor → { has_monitor: false, monitors: [] }.
{
"has_monitor": true,
"monitors": [
{
"monitor_id": "mon_3c1", "domain": "acme.com", "enabled": true,
"last_scan_at": "2026-05-29T05:00:00Z", "next_scan_at": "2026-05-30T05:00:00Z",
"latest_scan": {
"scan_id": "scan_5b2", "finished_at": "2026-05-29T05:03:41Z",
"urls_checked": 184, "health_score": 92,
"issue_counts": { "critical": 0, "warning": 3, "info": 9 },
"aeo_score": 78,
"aeo_issue_counts": { "critical": 1, "warning": 4, "info": 6 }
}
}
]
}GET/projects/:id/analytics/health/monitors/:mid/scans/:sid/issueshealth-issues.json
Issues from a scan. Returns { items, count, next_cursor }. Cursor-paginated: follow next_cursor (pass back as ?cursor=) until null; ?limit= defaults to 2000. There are no severity/category filter params (filter client-side).
{
"items": [
{
"scan_id": "scan_5b2", "rule_id": "missing_meta",
"severity": "warning", "category": "seo",
"url": "https://acme.com/pricing", "url_hash": "…",
"message": "Page is missing a meta description.",
"recommendation": "Add a 140-160 char description summarising the page.",
"evidence": {}
}
],
"count": 47,
"next_cursor": null
}GET/projects/:id/analytics/ranksranks.json
Tracked keywords under items, each with a history array of { date, position, source }. top_wins_this_week carries the previous-position / jump deltas. ?days default 30, max 90.
{
"project_id": "prj_8fa21c",
"window_days": 30,
"fetched_at": "2026-05-29T06:00:00Z",
"schedule": { "cadence": "daily", "interval_hours": 24,
"last_run_at": "2026-05-29T06:00:00Z", "next_run_at": "2026-05-30T06:00:00Z" },
"items": [
{
"keyword": "answer engine optimization",
"current_position": 6, "last_fetched_date": "2026-05-29", "current_source": "gsc",
"history": [
{ "date": "2026-05-23", "position": 9, "source": "gsc" },
{ "date": "2026-05-29", "position": 6, "source": "gsc" }
]
}
],
"top_wins_this_week": [
{ "keyword": "answer engine optimization",
"current_position": 6, "previous_position": 9, "jump": 3 }
]
}