SOV Tracker API

All API requests require a Bearer token in the Authorization header. Get your key from /dashboard/settings → API Erişimi.

Authorization: Bearer avt_live_xxxxxxxxxxxxxxxxxxxxxxxx

Returns the current SOV score across all platforms based on the most recent completed scan.

Request

curl -H "Authorization: Bearer $SOVTRACKER_KEY" \
  https://sovtracker.com/api/v1/sov

Response (200 OK)

{
  "scan_id": "scan_abc123",
  "completed_at": "2026-05-06T12:34:56Z",
  "avg_sov": 42,
  "platform_breakdown": {
    "chatgpt": 60,
    "claude": 35,
    "gemini": 50,
    "perplexity": 25,
    "ai_overviews": 40
  }
}

List recent scans (most recent first). Use limit query param (max 50, default 10).

curl -H "Authorization: Bearer $SOVTRACKER_KEY" \
  "https://sovtracker.com/api/v1/scans?limit=20"

Response

{
  "scans": [
    {
      "id": "scan_abc123",
      "status": "completed",
      "scan_type": "manual",
      "started_at": "2026-05-06T12:30:00Z",
      "completed_at": "2026-05-06T12:34:56Z"
    }
  ]
}

Trigger a new scan. Counts against your monthly scan quota. Body is optional.

curl -X POST \
  -H "Authorization: Bearer $SOVTRACKER_KEY" \
  -H "Content-Type: application/json" \
  https://sovtracker.com/api/v1/scans

Response (202 Accepted)

{
  "scan_id": "scan_xyz789",
  "status": "running",
  "estimated_seconds": 60
}

Time Machine: the dated raw AI answer archive. Every scan result is archived with its full raw response — "what did ChatGPT answer for this prompt on July 17, 2026?". This history cannot be backfilled later; it only exists because it was recorded on that day.

Query parameters

• keyword_id — filter by keyword (UUID)
• platform — chatgpt | claude | gemini | perplexity | ai_overviews
• from, to — ISO 8601 date range
• limit — 1-100, default 50
• cursor — pagination: pass meta.next_cursor from the previous response

curl -H "Authorization: Bearer $SOVTRACKER_KEY" \
  "https://sovtracker.com/api/v1/archive?platform=chatgpt&from=2026-06-01&limit=25"

Response (200 OK)

{
  "data": [
    {
      "id": "9f1c...",
      "scan_id": "scan_abc123",
      "platform": "chatgpt",
      "keyword_id": "kw_123",
      "prompt_used": "best crm tools for smb",
      "raw_response": "The most recommended CRM tools are...",
      "brand_mentioned": true,
      "mention_count": 2,
      "mention_position": 3,
      "sentiment": "positive",
      "sov_score": 42.5,
      "created_at": "2026-07-17T09:12:00Z"
    }
  ],
  "meta": {
    "count": 1,
    "next_cursor": "MjAyNi0wNy0xN1...",
    "plan_window_applied": false,
    "window_start": "2026-06-01T00:00:00.000Z"
  }
}

History depth is plan-enforced server-side, but this only matters in the dashboard: Free (limited to the last 7 days there) and Starter can't call the API at all — API access requires Pro or above, and every plan from Pro up gets the full archive. So in an actual API response, meta.plan_window_applied is effectively always false.

Connect an AI assistant that supports Streamable HTTP and Authorization headers to your SOV data. The server speaks Streamable HTTP and authenticates with the same API key as the REST API (Pro plan and above). All tools are read-only and scoped to the organization that owns the key.

https://sovtracker.com/api/mcp

Get your API key from /dashboard/settings → API Access — the MCP client sends it as an Authorization header on every request.

Available tools

• get_visibility_summary — latest scan: overall SOV, per-platform score/mentioned, trend vs previous scan
• list_keywords — tracked keywords with current status
• get_scan_results — per-result rows for a scan, filterable by platform/keyword
• get_answer_archive — Time Machine: dated raw AI answers (plan history depth applies)
• get_business_card — entity card status: trust score, field-group freshness, attestation date
• get_ai_traffic — AI referrer signals and AI-tag-only visits, reported separately

No write or scan-trigger tools are exposed — your assistant can read the records available to its organization, scope and plan without spending scan quota.

Claude Code

Add to .mcp.json for Claude Code:

{
  "mcpServers": {
    "sov-tracker": {
      "type": "http",
      "url": "https://sovtracker.com/api/mcp",
      "headers": {
        "Authorization": "Bearer avt_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor supports a remote URL and Authorization header in .cursor/mcp.json. Claude.ai requires an organization administrator with request-header authentication beta access; enter the endpoint and Authorization: Bearer key together. ChatGPT direct connection with this Bearer key is not yet validated.

Generic Streamable HTTP client

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://sovtracker.com/api/mcp"),
  {
    requestInit: {
      headers: { Authorization: "Bearer avt_live_xxx" },
    },
  }
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const tools = await client.listTools();
const summary = await client.callTool({
  name: "get_visibility_summary",
  arguments: {},
});

Rate limit: 60 requests/min per key. 401 = missing/invalid key or plan below Pro; 429 = rate limited.

Receive HTTP POST notifications when events fire. Configure URLs and events at /dashboard/settings → Outbound Webhooks.

Available events

• scan.completed — fires when a scan finishes
• sov.dropped — SOV crossed alert threshold downward
• mention.detected — new brand mention found
• competitor.overtake — a competitor pulled ahead

Precondition: the last three events are evaluated by the alert engine, so each one fires only while its matching rule is enabled under Settings → Alerts (sov.dropped → SOV Drop, mention.detected → New Mention, competitor.overtake → Competitor Overtake). They are delivered at the same moment as the corresponding alert e-mail. scan.completed has no such precondition.

Payload

{
  "event": "scan.completed",
  "organization_id": "org_abc",
  "timestamp": "2026-05-06T12:34:56Z",
  "data": {
    "scan_id": "scan_xyz",
    "avg_sov": 42,
    "results_count": 50,
    "mentioned_count": 21
  }
}

Signature verification

Each request includes an X-Sovtracker-Signature header (HMAC-SHA256 hex of the raw body, signed with your webhook secret).

import crypto from 'crypto';

function verify(rawBody, headerSig, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(headerSig)
  );
}

• 401 — Missing or invalid API key
• 403 — Plan does not include API access (upgrade to Pro+)
• 429 — Monthly scan quota exhausted
• 500 — Server error — retry with exponential backoff