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: Free sees the last 7 days only; Starter and above get the full archive. When the window trims your requested range, meta.plan_window_applied is true and meta.window_start shows the effective start.

Connect your own AI assistant — Claude (Desktop / claude.ai), ChatGPT connectors, Cursor, or any MCP client — directly 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 — last-30-days AI referral visits by source

No write or scan-trigger tools are exposed — your assistant can read everything but cannot spend your scan quota.

Claude Desktop / Claude Code

Add to claude_desktop_config.json (or .mcp.json for Claude Code):

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

On claude.ai (web), add it under Settings → Connectors → Add custom connector with the same URL. Cursor uses the same JSON shape in .cursor/mcp.json.

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

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