Tracker API endpoints

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

Lifecycle

A tracker reruns 1–30 prompts weekly or monthly for one measurement: rankings, compare, citations, or sentiment. 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"
  }
}

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 weekly or monthly frequency, IANA timezone, HH:mm time, and weekday (0–6) or monthday (1–31). 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.

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.