Skip to main content
You create a monitor once. Each run is a set of ordinary async tasks, billed at each engine’s price. This page covers creating, running and managing monitors. Reading the numbers is in Reports and metrics, the answers behind them in Sources and answers, and webhooks and email alerts in Events and alerts. For the dashboard view of the same data, see the product page.

Brand and category monitors

A monitor has a mode, 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. position is the character offset of the first match, or null when the brand is absent.
  • Cited: the answer cites a page on one of your domains or a subdomain of it.
  • Competitor hits: which of the monitor’s competitors appear in the same answer.
These scores carry no sentiment and no estimate of market share. A category monitor’s rank is a place among the brands the answers name, nothing more. For sentiment and recommendations per answer, turn on 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

Read quality first, then stats, brands and opportunities. Every field is explained in Reports and metrics.
To get answers before the next scheduled run, call 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 carry source: "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. competitorsReadAt says when the last read ran.
  • On update, competitors replaces your own list and keeps the found ones. Entries with source: "auto" in the request are ignored, so you can send back what GET returned.

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’s intervalHours, up to 168. The engine joins every k-th run, counting from the first run, which every engine joins.
An entry can only name one of the monitor’s engines and accepts only these two keys. On update, 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:
  • location asks every prompt from one point, in decimal degrees.
  • grid asks every prompt from each point of a square grid around center. size is 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.
Only 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 in answer.analysis from GET /v1/monitors/{id}/answers/{taskId}.
Reading reports, sources, answers and results costs nothing.
The schedule repeats until you pause or delete the monitor. The monthly figure above is what you commit to when you create it.
How the schedule behaves:
  • 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_ERROR naming 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. nextRunAt is when the next run becomes due. Resuming a paused monitor, or changing intervalHours, 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.
For example:
Suggestions that contain the brand name or an alias are removed. Review the list before you create the monitor. You can request one suggestion every 20 seconds and 30 per hour; more returns 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.
The response carries the queued task in 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 with promptTopics:
A category monitor has no brand of its own: 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: false pauses the monitor; enabled: true resumes it with the next run one interval from now. Pauses appear in reports as pauses.
  • Changing alertBelowPct re-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 at https://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:
  1. GET /v1/monitors/capabilities: engines, prices and limits before spending anything.
  2. GET /v1/monitors: reuse a monitor for the topic and market, or create one, optionally starting from POST /v1/monitors/suggest.
  3. POST /v1/monitors/{id}/run only if you need answers before the next scheduled run.
  4. GET /v1/monitors/{id}/analytics?days=30: read quality before the numbers, and wait until health.pending reaches 0.
  5. GET /v1/monitors/{id}/sources?days=30&groupBy=page: follow nextCursor to the end.
  6. GET /v1/monitors/{id}/answers/{taskId}: open the answer behind the top entry in opportunities before acting on it.
  7. GET /v1/monitors/{id}/results?since=...&until=...&format=csv: export the same window, following x-next-cursor until 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.