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.
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
Inputs, results, and limits
- Create:
nameis 1–100 characters. Set daily, weekly or monthlyfrequency, IANAtimezoneand HH:mmtime. Weekly also takesweekday(0–6) and monthlymonthday(1–31); daily needs neither. An out-of-range monthday runs on that month’s last day. - Definition: one
primitiveand 1–30prompts. Shared fields arecompetitorsfor rankings/compare,brandfor compare/sentiment, and optionalurlfor citations. Unused fields are rejected. Limit: 25 trackers per account. - Surfaces:
modelsapplies to every prompt. Omit it for the three defaults or list models explicitly; trackers have nofullSweep. - Update:
PATCHreplaces the whole definition. Send every field; any edit returns to Draft and clears recurring authorization. - Manual runs:
requestTokenis 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
pauseReasonwhen 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.