Tracker API endpoints

Create daily, weekly or monthly trackers over AI rankings, comparisons, citations, sentiment or Google keyword rankings, confirm the per-run cost, then read stored results over REST.

Lifecycle

A tracker reruns 1–30 prompts daily, weekly or monthly for one AI measurement: rankings, compare, citations, or sentiment; or it checks 1–100 keywords for one site with keyword_rankings. It stores results and changes.

  • DRAFT: saved, with no runs enabled.
  • ACTIVE: scheduled and manual runs enabled.
  • PAUSED: future runs stop; configuration and history remain.
Recurring billing
Activation authorizes billed runs until pause. Copy estimatedCostMicroPerRun exactly into maxCostMicroPerRun; Cite42 pauses before any run above that limit.

Create and activate

1. Create a Draft tracker

This example runs weekly on Monday (weekday: 1; Sunday is 0).

curl -X POST https://www.cite42.dev/api/v1/trackers \
  -H "Authorization: Bearer $CITE42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme CRM weekly visibility","cadence":{"frequency":"weekly","timezone":"Europe/London","time":"09:00","weekday":1},"primitive":"rankings","competitors":["Acme CRM","Rival CRM","Legacy CRM"],"models":["chatgpt","perplexity","gemini"],"prompts":["best startup CRM","Which startup CRM is quickest to set up?","What CRM should a small sales team use?"]}'

Review the returned estimate before activation:

{
  "tracker": {
    "id": "6d9d6580-4cef-4b84-8804-2e90d9e57c9a",
    "name": "Acme CRM weekly visibility",
    "status": "DRAFT",
    "cadence": {
      "frequency": "weekly",
      "timezone": "Europe/London",
      "time": "09:00",
      "weekday": 1
    },
    "primitive": "rankings",
    "prompts": [
      "best startup CRM",
      "Which startup CRM is quickest to set up?",
      "What CRM should a small sales team use?"
    ],
    "brand": null,
    "competitors": [
      "Acme CRM",
      "Rival CRM",
      "Legacy CRM"
    ],
    "url": null,
    "models": [
      "chatgpt",
      "perplexity",
      "gemini"
    ],
    "estimatedCostMicroPerRun": 39000,
    "maxCostMicroPerRun": null,
    "nextRunAt": null,
    "lastRunAt": null,
    "pauseReason": null,
    "createdAt": "2026-08-17T08:30:00.000Z",
    "updatedAt": "2026-08-17T08:30:00.000Z"
  }
}

An AI tracker can also set country, plus language for Google AI Overviews and ChatGPT, to measure every prompt from that country. Leave it out for each surface’s default. On an update, leaving country out keeps the tracker’s market and null removes it. Trackers can include chatgpt_app in models: ChatGPT itself, captured from its web interface, next to the OpenAI API surface chatgpt.

A Google rankings tracker takes keywords (each with an optional target page), a domain, and optionally country, device and up to five competitors, instead of prompts and AI surfaces. Each keyword is one check per run at $0.09 per keyword, so this two-keyword tracker estimates $0.18 per run. Every check is fresh. A keyword that moves ten places or more, or into or out of the top 10 or top 100, is checked a second time straight away: if both checks move the same way the stored result is marked confirmed, otherwise unconfirmed and reported without a rise or drop. Only moves of five places or more, or across the top 3 or top 10, are reported as changes.

curl -X POST https://www.cite42.dev/api/v1/trackers \
  -H "Authorization: Bearer $CITE42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"acme.example Google rankings (US)","cadence":{"frequency":"weekly","timezone":"America/New_York","time":"09:00","weekday":1},"primitive":"keyword_rankings","domain":"acme.example","country":"us","device":"desktop","competitors":["rival.example"],"keywords":[{"keyword":"best startup CRM","page":"/startup-crm"},{"keyword":"crm for startups"}]}'

2. Confirm the exact estimate

Send the returned integer unchanged. If it changes, activation returns 409 cost_estimate_changed with the new amount.

curl -X POST https://www.cite42.dev/api/v1/trackers/6d9d6580-4cef-4b84-8804-2e90d9e57c9a/activate \
  -H "Authorization: Bearer $CITE42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"maxCostMicroPerRun":39000}'

The response includes status: "ACTIVE", the accepted maximum, and nextRunAt.

Run now and read results

Queue an immediate run

An Active tracker needs a new, non-secret requestToken per run. Reuse it only to retry that run: a new run returns 202; a replay returns 200 without another charge.

curl -X POST https://www.cite42.dev/api/v1/trackers/6d9d6580-4cef-4b84-8804-2e90d9e57c9a/runs \
  -H "Authorization: Bearer $CITE42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestToken":"weekly-ai-visibility-2026-08-17"}'

Read stored history

Poll the report for status and results. It returns 20 runs by default; limit accepts 1–100.

curl -X GET https://www.cite42.dev/api/v1/trackers/6d9d6580-4cef-4b84-8804-2e90d9e57c9a/report?limit=20 \
  -H "Authorization: Bearer $CITE42_API_KEY"

{ tracker, runs } lists newest runs first, with status, costs and prompt results. Comparable completed results include a delta. Percentage-point changes need at least 10 answers per group and do not prove cause.

Operations

GET /v1/trackers
200
List every tracker owned by the authenticated account.
POST /v1/trackers
201
Create a Draft tracker and return its current per-run estimate.
GET /v1/trackers/:id
200
Read one tracker, including its prompts, measurement, schedule, and status.
PATCH /v1/trackers/:id
200
Replace the whole tracker definition. Every edit returns the tracker to Draft.
DELETE /v1/trackers/:id
200
Delete a Draft or Paused tracker after queued and running work finishes.
POST /v1/trackers/:id/activate
200
Confirm the exact current estimate and start or resume recurring runs. Returns a billing block, and 402 when the balance cannot cover the next run.
POST /v1/trackers/:id/pause
200
Stop future scheduled runs while preserving configuration and history.
POST /v1/trackers/:id/runs
202 / 200 replay
Queue an immediate billed run with an idempotent request token.
GET /v1/trackers/:id/report
200
Read the tracker and its newest stored runs, results, changes, and costs.

Inputs, results, and limits

  • Create: name is 1–100 characters. Set daily, weekly or monthly frequency, IANA timezone and HH:mm time. Weekly also takes weekday (0–6) and monthly monthday (1–31); daily needs neither. An out-of-range monthday runs on that month’s last day.
  • Definition: one primitive and 1–30 prompts. Shared fields are competitors for rankings/compare, brand for compare/sentiment, and optional url for citations. Unused fields are rejected. Limit: 25 trackers per account.
  • Surfaces: models applies to every prompt. Omit it for the three defaults or list models explicitly; trackers have no fullSweep.
  • Update: PATCH replaces the whole definition. Send every field; any edit returns to Draft and clears recurring authorization.
  • Manual runs: requestToken is 1–200 characters; at most three may be queued or running per account.
  • Delete: pause first and wait for queued/running work. Configuration and history are removed; financial records remain.
  • Results: runs can be Queued, Running, Completed, Partial, or Failed. Check pauseReason when a tracker pauses automatically.

Billing and automatic pauses

Management and reports are free. Scheduled and manual runs bill only successful prompts at current rates; reports show estimatedCostMicro and billedCostMicro.

Here, 3 prompts across three surfaces estimate at $0.39 per run, about $1.69 monthly at current prices. Activation approves the per-run maximum, not the projection.

402 insufficient_credits means the balance cannot cover one run. Otherwise, activation returns the balance, per-run cost, and runsDryAt estimate. estimatedOverWeeklySpendLimit flags active trackers estimated to average more than the account's $100 rolling seven-day limit; it is an average that excludes other usage, and a tracker paused by the limit stays paused until you resume it.

Cite42 pauses for higher estimates, low funds, spend limits, closed accounts, or invalid inputs/schedules. Email covers activation, runs, pauses, and deletion; there are no webhooks. Poll status and pauseReason.