Brand and category monitors
A monitor has amode, set when you create it and fixed for its life, because it decides what every
stored answer means.
Each answer is scored once, when it arrives:
- Mentioned: one of your aliases appears in the answer text.
positionis the character offset of the first match, ornullwhen the brand is absent. - Cited: the answer cites a page on one of your
domainsor a subdomain of it. - Competitor hits: which of the monitor’s competitors appear in the same answer.
analysis.
Quick start
1
Create the monitor
The first run starts as soon as the monitor is created.The response is
201 with the stored monitor. Keep data.monitor.id.2
Wait for the answers
Tasks are admitted as your plan’s concurrency allows, so a run arrives over seconds to minutes.
The report’s
health.pending counts the tasks still in flight. Read the report once it reaches 0.3
Read the report
quality first, then stats, brands and opportunities. Every field is explained in
Reports and metrics.POST /v1/monitors/{id}/run.
Create a monitor
POST /v1/monitors (reference) validates the definition,
checks it against your account’s limits, stores it and starts the first run. The call returns 201
before that run finishes. If the first run cannot start (for example, your balance is too low), the
monitor is still created and the scheduler retries the run every minute.
For example, the quick start request returns:
Request fields
Every list field accepts a JSON array or one newline-separated string. Entries are trimmed, blank entries are dropped and duplicates are removed.Engines
A monitor can schedule the prompt-based answer engines:CHATGPT, GEMINI, PERPLEXITY, GOOGLE
(Google AI Overviews), AIMODE (Google AI Mode), NAVER_AI_BRIEF, NAVER_AI_TAB, and NAVER, a
deprecated name kept for existing monitors. The aliases GOOGLE_AIO, GOOGLE_AIMODE and
NAVER_AI_MODE are accepted and stored as GOOGLE, AIMODE and NAVER_AI_TAB. Engine names are
case-sensitive. Search, web data and analysis task types, such as GOOGLE_SERP or CITATION_ANALYSIS,
cannot be scheduled. Prices and per-engine details are in the engine catalog.
An API key restricted to some engines can only create, update or run monitors that use those engines;
anything else returns 403 KEY_SCOPE_DENIED.
Competitors
You do not have to list competitors. After the first run, a weekly read of the monitor’s recent answers adds the brands that sell what you sell and appear in at least two answers: up to 15 on a brand monitor, 25 on a category monitor.- Found competitors carry
source: "auto"; the ones you list carrysource: "user". The read never changes or removes yours. A found brand that the next two reads both miss is removed. - When the found list changes, the monitor’s stored answers are scored again against it, so every brand
in a report is measured over the same answers.
competitorsReadAtsays when the last read ran. - On update,
competitorsreplaces your own list and keeps the found ones. Entries withsource: "auto"in the request are ignored, so you can send back whatGETreturned.
How names are matched
- Matching ignores case and character width (NFKC).
- Names in Latin script match whole words only: “replicates” is not a mention of a brand called Replicate. A Korean, Japanese, Chinese or Thai letter next to the name counts as a word break, so “agoda를” and “ahamoが” mention agoda and ahamo. Korean, Japanese, Chinese and Thai names match anywhere in the text.
- A one-character name never matches. Give such a brand a longer alias.
- When two names overlap, the one that starts first, then the longer one, counts. “Acme” inside a competitor named “Acme Pro” is the competitor.
- Link targets, bare URLs and citation chips are removed before matching; the visible text of a link is
kept. A citation counts toward
cited, not toward a mention.
Write prompts that measure something
- One monitor per topic and market. “best CRM” and “how do I price a CRM” are different intentions; averaging them hides both.
- Phrase prompts as a buyer would, and never include your own brand. A prompt that names the brand is always a mention, so it reports 100% and measures nothing. Competitor names in prompts are fine.
Samples and per-engine cadence
AI answers change from one session to the next, so a share of several answers is steadier than one.engineSettings sets, per engine, how many answers to collect per prompt and how often the engine runs:
samples: 1–10 answers per prompt and point in each run (default 1). Each is a separate task in its own session, scored and billed like any other.intervalHours: a multiple of the monitor’sintervalHours, up to 168. The engine joins every k-th run, counting from the first run, which every engine joins.
engineSettings replaces the stored value; an update that drops an engine drops its entry, and one that
changes the monitor’s intervalHours checks the engine intervals against the new value.
Location and grids
By default every task asks for the country as a whole. To measure local answers:locationasks every prompt from one point, in decimal degrees.gridasks every prompt from each point of a square grid aroundcenter.sizeis the points per side: 3, 5, 7 or 9 (9 to 81 points).radiusMeters, 100 to 50,000, is the distance from the center to the middle of an edge.
CHATGPT, GEMINI, GOOGLE and AIMODE answer for a location. A monitor with a location or grid
and any other engine is rejected with 400 VALIDATION_ERROR. On update, setting one of location and
grid clears the other, and null clears it. Read the answers per point with
GET /v1/monitors/{id}/grid.
Cost and scheduling
A run creates, for each engine that joins it, one task per prompt, per point and per sample:points is 1 without a grid. For example, 12 prompts on CHATGPT (1 credit) and GOOGLE (1.25 credits)
is 24 tasks and 27 credits per run, about 810 credits a month at a daily interval. With
"CHATGPT": { "samples": 5 } the same monitor is 72 tasks and 75 credits per run. Read current prices
from GET /v1/monitors/capabilities rather than hardcoding them; how credits are held
and charged is in Credits and limits.
Two charges come on top of the tasks:
- Competitor read: 80 credits per 30 days per monitor, split across its runs by cadence (about 2.67 credits per run for a daily monitor, 18.67 for a weekly one). It is charged when a run’s tasks are all submitted, so a run your balance stopped costs nothing for it.
- Answer analysis: with
analysis: true, 1 credit per task, charged only for answers that were analyzed. The scores (mentioned,cited,position) are unchanged; each answer’s result is inanswer.analysisfromGET /v1/monitors/{id}/answers/{taskId}.
- A run is not a burst. Tasks are submitted as your plan’s concurrency and the engine queues allow. Every minute the scheduler continues where it stopped, one task per engine in turn, and monitors of different accounts take turns. A parent account and its sub-accounts share one set of turns.
- A run must fit its interval. If one engine’s tasks cannot be admitted before that engine runs
again, create and update return
400 VALIDATION_ERRORnaming the shortest interval that fits. A run still submitting when a full interval has passed is closed, and its remaining tasks are not sent. - Missed runs are not replayed.
nextRunAtis when the next run becomes due. Resuming a paused monitor, or changingintervalHours, schedules the next run one interval from that moment.
Capabilities
GET /v1/monitors/capabilities (reference) returns, for your
account: each schedulable engine with creditsPerTask, analysisCreditsPerTask, your limits, the
modes, the metric definitions (metrics), the schedule formulas and the change event types. It has no
side effects and costs nothing; call it before creating monitors programmatically.
Choose prompts
Suggest prompts from brand facts
POST /v1/monitors/suggest (reference) returns up to 12
candidate prompts written as a buyer in country would ask. It saves nothing and spends no credits.
429 RATE_LIMITED. When the model declines the brand the call returns 400 SUGGEST_FAILED, when the
suggestion service fails 502 SUGGEST_FAILED, and when it is not configured 503 SUGGEST_FAILED.
Research prompts from search demand
POST /v1/monitors/research (reference) takes the request
body of Prompt Research, costs the same 11 credits and returns the same
result as a task owned by your account.
data.task, with data.credits and data.replayed. Read the
result with GET /v1/async/task/{id} using data.task.id (see Async tasks).
Then create the monitor with monitorSet.prompts[].prompt as prompts; on a category monitor, each
prompt’s topic as its entry in promptTopics and brands[].brand as competitors. Nothing is saved
until you create the monitor.
With monitorEngines, research checks monitorSize × engines against a fixed 200 tasks per run and
assumes one point and one sample per engine, so a set it accepts can still be refused once you add
samples or a grid. See Sizing the set for a monitor.
Category monitors
A category monitor ranks the brands the engines name for a market. Group its prompts by sub-field withpromptTopics:
aliases, domains and alertBelowPct must be empty, or the
request returns 400 VALIDATION_ERROR, and it has no alert. Its stats.mentioned and stats.cited in
GET /v1/monitors are always 0; the list adds leader, the brand named most in the last 30 days. Its
report is described in Category reports. Schedule, cost, sources,
answers, results and change events work as on a brand monitor, except that a category monitor sends only
monitor.source.first_cited events.
On update, an edit to prompts drops the promptTopics entries of removed prompts. The answers those
prompts collected stay in the leaderboard.
Manage monitors
The older period summary in
GET /v1/monitors/{id} is kept for compatibility. For numbers, use
/analytics: the older summary mixes an all-time matrix of the latest
answer per prompt and engine into windowed numbers, cuts sources at 12 domains and 20 pages, and its
shareOfVoice counts each brand against all answers, so the shares can add up to more than 100.
A monitor that belongs to another account returns 404 NOT_FOUND, not 403.
Update a monitor
PATCH takes any subset of the create fields and validates the result as a whole, against the same
limits. Fields you omit keep their values.
enabled: falsepauses the monitor;enabled: trueresumes it with the next run one interval from now. Pauses appear in reports aspauses.- Changing
alertBelowPctre-arms the alert. - Changing aliases, domains or competitors affects answers scored from then on. Stored answers keep the definitions they were scored with, so reports withhold comparisons across the change (see Reports and metrics).
Run a monitor now
POST /v1/monitors/{id}/run makes the next run due immediately; the scheduler starts it within about a
minute and returns data.queued: true. The run is charged like a scheduled one. Calling it again while
that run is still due does not create a second run.
Before queueing, the call checks that your balance covers the run, including the competitor read and
analysis credits. If it does not, it returns 402 INSUFFICIENT_CREDITS with details.needed and
details.available. A sub-account over its monthly credit limit gets 429 SUB_ACCOUNT_CREDIT_LIMIT. A
paused monitor returns 404 NOT_FOUND: resume it first.
Share a report
You can publish one monitor’s report athttps://querying.ai/<slug>. A shared report shows the
analytics, sources, citations, results and answers; it never shows settings, alerts, the run controls or
your account’s task health.
GET /v1/monitors/{id}/share (reference) returns the current state,
access, slug, locale and url, plus a suggestedSlug when none is set.
PUT /v1/monitors/{id}/share (reference) changes it:
Setting
access to PRIVATE takes the report offline and keeps the slug, so turning sharing on again
reuses the same address.
Use monitors from an agent
The MCP server exposes monitors as tools:get_monitor_capabilities, list_monitors,
get_monitor, create_monitor, update_monitor, delete_monitor, run_monitor,
get_monitor_analytics, get_monitor_sources, get_monitor_results, get_monitor_answer,
suggest_monitor_prompts, get_monitor_alerts and test_monitor_alert. Each makes one API call with your
key.
A practical sequence for an agent or a script:
GET /v1/monitors/capabilities: engines, prices and limits before spending anything.GET /v1/monitors: reuse a monitor for the topic and market, or create one, optionally starting fromPOST /v1/monitors/suggest.POST /v1/monitors/{id}/runonly if you need answers before the next scheduled run.GET /v1/monitors/{id}/analytics?days=30: readqualitybefore the numbers, and wait untilhealth.pendingreaches0.GET /v1/monitors/{id}/sources?days=30&groupBy=page: follownextCursorto the end.GET /v1/monitors/{id}/answers/{taskId}: open the answer behind the top entry inopportunitiesbefore acting on it.GET /v1/monitors/{id}/results?since=...&until=...&format=csv: export the same window, followingx-next-cursoruntil it is empty.
Limits
A contract account is one with a negotiated concurrency limit. These apply to every account:
Report, page-size and retention limits are listed on the pages that use them:
Reports and metrics, Sources and answers and
Events and alerts.
Errors
The error envelope is the same as everywhere else (see Errors). Codes specific to monitors:Next steps
Reports and metrics
The
/analytics contract and what each number means.Sources and answers
Cited pages, the answers behind each score, and exports.
Events and alerts
Webhooks when answers change, and email alerts on your mention rate.
Prompt Research
Find the prompts worth tracking from search demand.