API documentation

Takes no query parameters and is not paginated: the full list is returned in one response, ordered by created_at descending.

curl https://llmmetrix.com/api/v1/projects \
  -H "Authorization: Bearer llmx_xxxxxxxxxxxx"

{
  "data": [
    {
      "id": "8f14e45f-ceea-467a-9cbe-3e2f5d1b7a90",
      "domain": "acme.com",
      "brand_name": "Acme",
      "industry": "B2B SaaS",
      "competitors": ["globex.com", "initech.com"],
      "engines": ["chatgpt", "perplexity", "gemini", "claude"],
      "created_at": "2026-04-02T09:14:22.881Z",
      "workspace_id": "1d2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b"
    }
  ]
}

If the key's owner belongs to no workspace, the response is {"data": []} rather than an error.

Pagination is limit + offset; page through history a window at a time. The endpoint reads the most recent window of history by default.

curl "https://llmmetrix.com/api/v1/scans?project_id=8f14e45f-ceea-467a-9cbe-3e2f5d1b7a90&limit=5" \
  -H "Authorization: Bearer llmx_xxxxxxxxxxxx"

{
  "data": [
    {
      "id": "b6c1a2d3-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "project_id": "8f14e45f-ceea-467a-9cbe-3e2f5d1b7a90",
      "status": "completed",
      "score": 62,
      "summary": "Acme is cited in 6 of 10 answers, most often behind Globex.",
      "created_at": "2026-07-29T07:03:11.402Z",
      "engine_results": [
        {
          "engine": "chatgpt",
          "label": "ChatGPT",
          "score": 71,
          "mentionRate": 0.8,
          "avgRank": 2.1,
          "sentiment": "positive",
          "prompts": 10
        }
      ],
      "prompt_results": [
        {
          "engine": "chatgpt",
          "label": "ChatGPT",
          "prompt": "best invoicing software for agencies",
          "mentioned": true,
          "rank": 2,
          "sentiment": "positive",
          "competitorsMentioned": ["Globex"],
          "citations": [
            {
              "url": "https://acme.com/pricing",
              "domain": "acme.com",
              "title": "Acme Pricing",
              "position": 1
            }
          ],
          "answerExcerpt": "For agencies, Acme and Globex are the two…",
          "answerText": "For agencies, Acme and Globex are the two most…",
          "claimsAboutBrand": ["Acme offers unlimited seats"],
          "accuracyRisk": "low"
        }
      ]
    }
  ]
}

Body: {"projectId":"…","competitor?":"…","region?":"…"}. The scan runs through the same gate ladder as the dashboard (cooldown, weekly/daily/monthly budget gates, payment suspension, per-user rate and concurrency caps), so a script cannot spend where the UI would refuse. Poll GET /api/v1/jobs/[jobId] until it reaches a terminal status, then read the answers via GET /api/v1/scans.

curl -X POST "https://llmmetrix.com/api/v1/scans" \
  -H "Authorization: Bearer llmx_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"8f14e45f-ceea-467a-9cbe-3e2f5d1b7a90"}'

{
  "jobId": "9f2f4e6d-5c4b-4a3b-9e8f-1a2b3c4d5e6f"
}

Visibility is the same three-tier union as the dashboard's activity page: jobs of projects in scope, jobs of workspaces the owner belongs to, and the owner's own user-tier jobs (exports, notifications). Optional filters: status (one of pending, processing, completed, failed, dead, canceled), type (e.g. scan), project_id, limit (default 50, max 100) and offset.

curl "https://llmmetrix.com/api/v1/jobs?status=failed&limit=10" \
  -H "Authorization: Bearer llmx_xxxxxxxxxxxx"

The poll endpoint for a triggered scan. The attempts/max_attempts pair answers the retryable-vs-give-up question. A job the key cannot see is 404, indistinguishable from a missing one. coverage carries the per-engine coverage snapshot for scan jobs (which engines returned nothing), never the full result payload.

curl "https://llmmetrix.com/api/v1/jobs/9f2f4e6d-5c4b-4a3b-9e8f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer llmx_xxxxxxxxxxxx"

{
  "data": {
    "id": "9f2f4e6d-5c4b-4a3b-9e8f-1a2b3c4d5e6f",
    "type": "scan",
    "status": "completed",
    "error": null,
    "attempts": 1,
    "max_attempts": 5,
    "project_id": "8f14e45f-ceea-467a-9cbe-3e2f5d1b7a90",
    "created_at": "2026-08-11T07:00:00.000Z",
    "updated_at": "2026-08-11T07:00:42.000Z",
    "started_at": "2026-08-11T07:00:00.000Z",
    "finished_at": "2026-08-11T07:00:42.000Z",
    "coverage": { "engines": ["chatgpt", "perplexity"], "failedEngines": [] }
  }
}

Restarts the same job row, so a re-run can never double-charge (the credit ledger is guarded on the job id). Gate notes: 409 when the job is not restartable or its row moved mid-flight; 402 for a suspended workspace or AI budget refusal; 403 for viewers. On top of the 60 writes/minute bucket, restarts are throttled at 5 / 10 minutes per user.

curl -X POST "https://llmmetrix.com/api/v1/jobs/9f2f4e6d-5c4b-4a3b-9e8f-1a2b3c4d5e6f/retry" \
  -H "Authorization: Bearer llmx_xxxxxxxxxxxx"

{
  "jobId": "9f2f4e6d-5c4b-4a3b-9e8f-1a2b3c4d5e6f",
  "restarted": true,
  "status": "pending"
}

project_id is required. An out-of-scope project reads as an empty list, never as another tenant's prompts. When a project has active tracked prompts, scans run exactly those instead of auto-generated discovery prompts.

Body: {"projectId":"…","text":"…"}, text 1–500 chars. At the cap the response is 402 { error, plan, limit }; deactivate one prompt or upgrade. The count is enforced under an advisory lock, so concurrent adds cannot slip past it.

Body: {"active": true | false}. Turning a prompt on is capped by the same per-plan active limit as creation; turning one off never is.

Same role gate as the dashboard's delete: the key owner must hold owner, admin or member in the prompt's workspace. Returns { ok: true }.

The body is validated strictly: unknown fields are rejected. The raw body is capped at 8 KB before parsing.

curl -X POST https://llmmetrix.com/api/collect \
  -H "Authorization: Bearer llmx_xxxxxxxxxxxx" \
  -H "Content-Type: text/plain" \
  -d '{
    "referrer": "https://chatgpt.com/",
    "page": "/pricing",
    "utm": { "source": "chatgpt", "medium": "ai_referral" }
  }'

// Classified as an AI referral and stored:
{ "ok": true, "stored": true, "source": "chatgpt", "matchedBy": "referrer" }

// Acknowledged but NOT an AI-attributed visit (deliberately not stored):
{ "ok": true, "stored": false }

Installing the beacon

You do not have to call /api/collect yourself. We ship a small tag that reads the referrer and utm_* parameters on page load and beacons them for you.

1. Mint a collector key. Open Dashboard → AI Traffic, select the project, and click Generate write key. The key is bound to that one project and is shown once; the snippet on that page comes pre-filled with it.
2. Paste the snippet into your site before </body>, or into a Google Tag Manager Custom HTML tag firing on All Pages.
   Install snippet

   <script async src="https://llmmetrix.com/tag.js"
           data-project="8f14e45f-ceea-467a-9cbe-3e2f5d1b7a90"
           data-key="llmx_xxxxxxxxxxxx"></script>

3. Serve it from the domain on the project. The beacon checks the browser's Origin against the project's domain: the apex and any subdomain of it are accepted (acme.com covers shop.acme.com, but not the other way round). A tag installed on an unrelated host is accepted with 200 {"ok":true,"stored":false}, not 403.
4. Tag your AI-facing links where you can. AI assistants frequently strip the referrer, so a utm_source is the reliable signal. Recognised sources are ChatGPT, Perplexity, Gemini, Claude, Copilot and Meta AI; the AI Traffic page has a link generator that emits correctly-tagged URLs.
5. Verify. Load a page with ?utm_source=chatgpt and confirm the beacon request returns {"ok":true,"stored":true} in your browser network panel. Referrals appear on the AI Traffic page.

The tag sends text/plain so the POST stays a CORS simple request and needs no preflight; it uses navigator.sendBeacon where available and falls back to fetch(…, { keepalive: true }). It sets no cookies and sends no personal data: referrer, path and utm_* only.

Authenticated with a full api key (a collector key is rejected). The route does no parsing itself: it validates, stores the body, queues a job and returns a job id.

curl -X POST https://llmmetrix.com/api/ingest/logs \
  -H "Authorization: Bearer llmx_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg c "$(tail -n 5000 /var/log/nginx/access.log)" \
    '{projectId:"8f14e45f-ceea-467a-9cbe-3e2f5d1b7a90", format:"combined", content:$c}')"

// 202, a new parse job was queued:
{ "jobId": "3f9a1c7e-2b44-4d1a-9f0e-77c5b8a3e112", "deduped": false }

// 200, identical content was already uploaded; collapsed onto the existing job:
{ "jobId": null, "deduped": true }