Tracker API

Create daily or weekly trackers over rankings, competitor comparisons, citations, and sentiment. Confirm the per-run cost before activation, then read stored results and changes over REST.

Lifecycle

A tracker stores 1 to 25 ordinary rankings, compare, citations, or sentiment inputs and reruns them daily or weekly. The tracker adds scheduling, stored run history, and comparable changes. It does not change how those four primitives measure or price a result.

• DRAFT: configuration and estimate are saved, but scheduled and manual runs cannot start.
• ACTIVE: scheduled runs are enabled, and Run now can queue an immediate run.
• PAUSED: future schedules stop while the saved configuration and run history remain available.

Create and activate

1. Create a Draft tracker

This example saves one weekly AI visibility check. Monday is weekday 1; weekday numbers run from 0 for Sunday through 6 for Saturday.

curl -X POST https://www.cite42.dev/api/v1/trackers \
  -H "Authorization: Bearer $CITE42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Weekly AI visibility","cadence":{"frequency":"weekly","timezone":"Europe/London","time":"09:00","weekday":1},"primitive":"rankings","competitors":["Cite42","Profound","Peec AI"],"models":["chatgpt","perplexity","gemini"],"prompts":["What are the best AI visibility tracking tools?","Which tools track brand mentions inside ChatGPT answers?","What should an agency use to report on AI search visibility?"]}'

The response contains the estimate you must review before activation:

{
  "tracker": {
    "id": "6d9d6580-4cef-4b84-8804-2e90d9e57c9a",
    "name": "Weekly AI visibility",
    "status": "DRAFT",
    "cadence": {
      "frequency": "weekly",
      "timezone": "Europe/London",
      "time": "09:00",
      "weekday": 1
    },
    "primitive": "rankings",
    "prompts": [
      "What are the best AI visibility tracking tools?",
      "Which tools track brand mentions inside ChatGPT answers?",
      "What should an agency use to report on AI search visibility?"
    ],
    "brand": null,
    "competitors": [
      "Cite42",
      "Profound",
      "Peec AI"
    ],
    "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. You cannot pad the first ceiling above the current estimate. If the estimate changed since the draft was read, this call returns 409 cost_estimate_changed with the new amount to review.

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}'

A successful response returns the tracker with status: "ACTIVE", the accepted maxCostMicroPerRun, and its first nextRunAt timestamp.

Run now and read results

Queue an immediate run

Manual runs require an Active tracker. Generate a new, non-secret requestToken for each intended run. Reuse that same token only when retrying the same run after an ambiguous network failure. A newly queued run returns 202; replaying the same token for the same tracker returns the same run with 200instead of billing a duplicate.

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

Use the report endpoint to poll run status and read results. REST returns the newest 20 runs by default; limit accepts 1 to 100. There is no separate per-run GET endpoint.

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

The response is { tracker, runs }. Runs are newest first and include the trigger, status, timestamps, estimated and billed cost, plus one item per tracked prompt. A completed item includes its primitive result and a delta when a previous result has the same saved input, model coverage, and methodology.

Operations

Tracker control and stored-history requests are free. The run endpoint queues one call per saved prompt, and the successful results are billed when background execution completes.

Inputs, results, and limits

• Create: name is 1 to 100 characters. A cadence has frequency daily or weekly, an IANA timezone, local time in HH:mm, and a required weekday for weekly trackers.
• Definition: one primitive — rankings, compare, citations, or sentiment — plus 1 to 25 prompts. The measurement’s own fields are set once for every prompt: competitors for rankings and compare, brand for compare and sentiment, an optional url for citations. A field a measurement does not use is rejected rather than stored. One account can own at most 25 trackers.
• Surfaces: models applies to every prompt. Omit it for the three default surfaces, or list them explicitly — there is no fullSweep on a tracker, so the stored list is exactly the one whose recurring cost was authorized. A read returns the resolved list.
• Update: PATCH replaces the whole definition, so send every field — a read returns the same shape to send back. Every edit returns the tracker to Draft and clears recurring authorization, including a name-only edit.
• Manual runs: requestToken is required and can be 1 to 200 characters. An account can have at most three manual runs queued or running at once.
• Delete: pause an Active tracker first and wait until no run is queued or running. Deletion removes tracker configuration and history but retains immutable financial records.
• Results: tracker status is Draft, Active, or Paused. Run status is Queued, Running, Completed, Partial, or Failed. Display pauseReasonwhen an automatic guardrail pauses a tracker.

Billing and automatic pauses

Create, list, read, edit, activate, pause, delete, and report calls cost 0 credits and do not return the ordinary primitive billing envelope. Scheduled and manual runs bill only the prompts that succeed, at their current per-model rates. Reports show estimatedCostMicro and the final billedCostMicro.

In this example, 3 prompts across three surfaces estimate at 39,000 micro-credits ($0.39) per run, so a weekly cadence projects to roughly 169,000 micro-credits a month. Activation authorizes the per-run amount only; the monthly figure is a projection at today’s prices. One displayed Cite42 credit equals 1,000 micro-credits, or $0.01.

Activation is refused with 402 insufficient_credits when the balance cannot cover a single run, because such a tracker would pause on its first run. Above that it is allowed: the activation response reports the balance, the per-run cost and runsDryAt, so a client can prompt for a top-up before runs stop. Enabling auto top-up keeps a schedule funded without intervention.

Cite42 can pause before further provider calls when the current estimate exceeds the accepted ceiling, credits or a spend limit are insufficient, the account closes, or a saved input or schedule is no longer valid. Account owners are emailed when a tracker pauses, and when a run reports changes, unless they switch those off in the dashboard. There are no webhooks yet, so an integration should still read status and pauseReason rather than waiting to be told.