Keep watching, pay per run, hear only what is new

Stored data

Table and Reading views

A monitor opens on its stored records in Table view. Reading view shows the same records as expandable cards. Search, source and date filters work on stored data; switching views does not run a check, send an alert or mark findings as read. Posted time and first-collected time are separate, with unknown or future publication times labelled.

Copy, CSV and JSON support selected rows, filtered results or all stored history. Multi-page exports stop visibly if they cannot establish a complete result; they never silently download a partial export. This is the history the monitor actually stored, not a promise of complete platform history. The console records export is separate from the bounded findings-export endpoint described below.

Settings, check history, costs and coverage remain available. Reports, stories, trends and feedback remain API capabilities; the default workspace is the records view, not the earlier report dashboard.

Builder

Say it in a sentence, review the whole monitor

The first thing on Monitors is a sentence box. “Tell me when people complain about Monzo on Reddit or Hacker News, daily” becomes a complete proposal: the template, the subject and any identifiers the sentence carries (a subreddit, an app id, a video link, a handle), the platforms — selected using this deployment’s registry and recorded evidence — the matching rule, the exclusions, the frequency, where alerts go, the cap and the estimated cost, each with the reason it was chosen. The deterministic pass reads what the sentence literally says; when a model is configured it proposes the judgement calls and is checked against the same catalogue, and identifier checks reject additions not grounded in the sentence. Review the proposal before activating it.

The proposal is a draft until you switch it on. The review page shows it in four questions with the monitor as it will run beside them; every edit is saved and re-priced; Test it first runs a check after confirmation and shows the resulting sample, matching reasons and cost. Available diagnostics depend on the monitor kind and retrieved evidence. Templates and “build your own” open the same review. Through the API: monitors/propose proposes, monitors/drafts saves, edits, activates and discards.

• Receipts. Each retained finding keeps a bounded copy of the evidence row it was made from and the reasons it matched. The stored evidence is available in the console and export; alerts link back to it. Its source link leads to the post or comment itself, or its discussion; the page it linked to is kept apart as the linked page. A post with no time, or a time in the future, is flagged and never counted as recent or as growth.
• Accounts and listings. Follow an account reads the account’s own timelines — an X handle (metered), a Bluesky handle, a YouTube channel — each optional and at least one; its items are the account’s own posts and videos, never mentions of its name. Reddit is not offered because the live Reddit endpoint returns a profile, not posts. New Google Maps reviews takes a pasted Maps link: a link with a Place id costs nothing to read, a place link is turned into the listing through one places search charged once, and a short link must be opened and pasted in full.
• Two exports. Stored retained findings from a window (CSV or JSON, with the bounded evidence record, linked page, time flag and kind of evidence), or the collected items recorded for one check — retained or excluded — with each item’s decision and reason, plus coverage showing which sources succeeded, failed, were skipped or hit a cap. Checks from before 5 September 2026 did not keep their collected items and say so.
• Storage limits. This is stored monitoring evidence, not a complete archive of a platform. Each check records at most 400 collected items, with collected text limited to 600 characters. In retained evidence records, individual text fields are limited to 1,500 characters; embedded comment collections and union fields are omitted. Open the source link for the original. Findings exports are limited to 5,000 rows per request and report when that limit is reached.
• Alert output. Each monitor has an output mode (output): report leads with what changed and why it matters, with receipts and labelled suggestions; everything lists new retained posts, comments or reviews. Intelligence templates default to a report; feeds, reviews and follow-alongs default to everything. This controls the saved output and notifications, not whether the console opens in Table or Reading view. Stored evidence and exports remain available in either mode, within the limits above.
• The report is composed, not written. Its developments, themes and disagreements start as the briefing’s claims. A model checks each one against the records it cites for its meaning — who said it, whether it was asserted, denied, doubted or asked, and when — and keeps it as written, rewrites it to what the records establish (keeping attribution, negation, doubt and time), or sets it aside. The checks a model cannot be trusted with stay deterministic: every name, number and date in the final sentence must be in the cited records, a quantifier (“users report”, “across platforms”, “debate”) needs enough firsthand accounts or platforms behind it, the engine’s own counted lines (“3 authors on…”, “the most active conversation”) are recounted from what this monitor holds, and claims about the same records become one development. The opening sentence and the names of discussions are checked the same way. Every line shows its records (a comment links to its thread; an unknown time says so) and the full set behind a count is one click away. What was set aside, and why, remains in the report diagnostics; the current default workspace shows records, not a Diagnostics report panel. With no model configured, no sentence is shown as checked: the report carries counts, discussions and records, and says so. When nothing reportable survived collection and filtering, the report says that with the counts, and nothing is sent.
• Accounts, not people. Every count is of distinct accounts per platform. Each record is counted by what it is: a firsthand claim (an account’s own words, with no affiliation Monocrawl recognises — which is not the same as independent), publisher coverage, a relayed item (a repost, a feed item, a headline passed on with its link), the subject’s own side, or an account Monocrawl cannot place. Several accounts passing the same story on are circulation, not several confirmations, so “circulated on three platforms” and “three accounts said it themselves” are different statements and both are shown. Nothing infers that an account is a person, and no identity is matched across platforms.
• New is not the same as newly found. A run tells posts made since the last check from older posts it only found now, and a new discussion from more posts on one it already knew; older posts found late never count as a rise, and the period comparison is by when posts were made.
• Accounts and periods. A run counts posts and distinct accounts per platform — the same person on two platforms counts twice, and the console says so — and compares the window with the one before it (the earlier half of a first window; after that the two periods by when posts were made). Acceleration, novelty and quiet are claimed only when both periods were collected alike: a first window that hit a platform’s page cap, or a platform that failed in one period, shows the counts with the limitation stated instead. The same discussion across platforms and runs is one topic and one story, keyed stably from run to run; unrelated posts stay apart.
• Verdicts are remembered. Mark a finding irrelevant and later runs hold back the same conversation, link, wording, topic and author until you change it. Mark it known or resolved and the same conversation, link, wording or topic stays quiet unless it changes materially — at least twice the posts it had, a platform it was not on, or a higher severity — and then it comes back with the reason stated on the finding and in the report, the verdict retired. Mark one useful and it guides the model. monitors/feedback, with scope=story to quiet a whole story.
• Export. monitors/export returns up to 5,000 retained findings in a window with their receipts and bounded evidence records as CSV or JSON. Use scope=collected for the items recorded for one check, including exclusions.

Workflows

Four guided workflows

The API also supports these four multi-source workflow presets. They combine subject, feed and change monitors into a grouped watch with per-source history. The current console starts with the sentence builder and template gallery described above, not the earlier seven-step workflow wizard. Availability and applicable rules depend on the selected targets.

A change check compares the new answer with the previous one under the workflow’s rules — price, availability, seller, rating, review count and tone, followers, new posts and engagement against the account’s own baseline, tracked ranks and the top-N band — and records each change as a finding with the value before, the value after, the rule that fired and the threshold it cleared. Moves below a threshold are ignored; findings below the minimum severity are not recorded; the same change is not repeated inside the cooldown (360 minutes by default) unless it gets worse. The first check records the baseline; changes are reported from the second.

Intelligence

Alerts, digests, stories, trends and reports

• Destinations, right away or as a summary. destinations on monitors/create and monitors/update is a JSON array of places, each with a kind (email, endpoint with an endpoint_id, or push), a cadence (immediate, daily, weekly) and, for immediate, a min_severity. A summary carries the period’s headlines, counts and top findings for that one monitor and goes out once a day (or on Mondays) after the account’s digest hour; a finding alerted right away still appears in the summary, because a summary is the period’s account, not a second alert. The account-wide digest (monitors/settings) still exists for those who want everything in one message. The older flags (delivery_email, delivery_webhook, delivery_mode, immediate_min_severity) are still accepted and are folded into destinations.
• Delivery. An alert is the report: in the console, by email, to the chosen Slack channel (Block Kit), Discord channel (an embed) or webhook (Monocrawl’s signed JSON, for your own service, Zapier, Make or n8n), and as a push notification on the devices that turned it on. monitors/test-delivery sends one clearly-marked sample alert to any destination and reports what it answered. Every run keeps a receipt per destination. A monitor switched on without a test shows as not tested until its first successful check.
• Stories. Related findings — the same topic across platforms and runs, the same rule on the same field, the same conversation, the same review source — grow one developing story instead of repeating alerts. A story alerts when it starts or escalates; repeats inside the cooldown wait for the digest; a story goes quiet after a day without news. monitors/stories lists them.
• Trends. monitors/trends returns findings per day, or any number a check records (price, rating, followers, rank), for the current period and the one before it, with the baseline and the comparison beside them. These series are available through the API; the current default console workspace is Table or Reading view.
• Reports. monitors/report saves a window of findings — or one story — in the research-report format: every fact cites the finding ids that support it, the report can be shared by link and exported as Markdown or JSON, and any generated interpretation is a separate block labelled as generated, with claims that cite no evidence dropped. Counted facts and generated interpretation are never mixed.
• Health and coverage. monitors/health reports the monitor’s state (ok, stale, failing, capped, paused), missed checks, each source’s successes, failures and reused answers, sources that are not live-proven on this deployment, recent errors, and what the shared cache avoided. monitors/analytics gives the account view: monitors by state, runs, findings by severity, duplicates held back, delivery success, credits against upstream cost, cache savings and time to the first useful finding.

Reliability

Leases, retries, refunds and limits

• A scheduled check is a job; a valid monitor lease prevents another worker from claiming the same check, and a job that already produced a recorded run is replayed rather than re-run after a restart. This is not an exactly-once guarantee across lease expiry or failures before a run is recorded.
• A failed check is recorded as an error run, refunded in full and never counted as a change. Retries back off — 15, 30, 60 minutes and so on up to the monitor’s own interval — and after ten failures in a row the monitor pauses itself and tells you why. Resuming clears the count.
• Three limits, checked before anything is charged: the monitor’s monthly cap, the account’s monthly budget across every monitor, and the balance. Over any of them the monitor is capped — paused by the system with the reason — and resumes on its own when the reason clears.
• A check accepts a shared answer only if it is younger than the monitor’s own interval and the route’s cache lifetime; older answers trigger a new retrieval. Eligible public results may be shared with other checks. A check served from a shared answer is free; a fresh fetch is charged the route’s price. Every run records where it was served from and what fetching it avoided.

Research → Monitor

From a briefing to a monitor

A completed Research briefing offers a monitor action. It prefills the resolved subject and its sense, the names kept out as namesakes, the platforms that actually answered, and a suggested name. Frequency, cap, delivery and activation are still yours to choose — review the prefilled subject and scope before activating it.

API

Creating and managing monitors through the API

The same monitors are available on /v1/monitors. Preview, create, read, list findings, run, update and delete — each below with a curl built from the registry’s own parameters. Replace the example monitor, draft, finding and job ids with ids from your own earlier responses. Resolve an ambiguous subject in preview before creating it. kind=subject follows a name across platforms; kind=feed reads one or more configured review, listing or timeline feeds; the original kind=change snapshots a page or endpoint.

1. 01monitors/previewlive · proven0 credits

   What a subject monitor would do, before it exists: the resolved subject or the senses to choose from, the recommended platforms with reasons, the schedule, the credit estimate from the price list, and a few pieces of no-cost evidence. Runs the free first pass only — no metered platform and no paid fallback is touched.

   curl

   curl "https://www.monocrawl.com/v1/monitors/preview?query=Monzo&purpose=complaints" \
     -H "x-api-key: mn_your_key_here"

2. 02monitors/testlive · proven0 credits

   Run one real check for a monitor that does not exist yet and see what you would have been told about. Charged like one run and refunded down to what was retrieved; nothing is recorded and nothing is sent.

   curl

   curl "https://www.monocrawl.com/v1/monitors/test?query=Monzo&purpose=complaints&confirm=true" \
     -H "x-api-key: mn_your_key_here"

3. 03monitors/createlive · proven1 credit

   Save a monitor and its schedule. A subject monitor follows a resolved name across platforms and records only what is new; a feed monitor records new items from one review or listing endpoint; a change monitor snapshots a page or endpoint. Creating costs the listed credits; each run of a subject or feed monitor is charged separately, up to its monthly cap.

   curl

   curl "https://www.monocrawl.com/v1/monitors/create?kind=subject&query=Monzo&purpose=complaints&schedule_minutes=360&monthly_cap_credits=200" \
     -H "x-api-key: mn_your_key_here"

4. 04monitors/getlive · proven0 credits

   One monitor with its target, schedule and the summary of its most recent run.

   curl

   curl "https://www.monocrawl.com/v1/monitors/get?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a" \
     -H "x-api-key: mn_your_key_here"

5. 05monitors/findingslive · proven0 credits

   The findings a subject or feed monitor has recorded, newest first: each with its platform, author, link, posted time, relationship to the subject and the purpose filters it matched. A finding is recorded once per monitor, however many runs see it.

   curl

   curl "https://www.monocrawl.com/v1/monitors/findings?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a&unseen=true" \
     -H "x-api-key: mn_your_key_here"

6. 06monitors/storieslive · proven0 credits

   The developing stories a monitor's related findings have been grouped into, with counts, severity and when each was last seen.

   curl

   curl "https://www.monocrawl.com/v1/monitors/stories?id=mon_%E2%80%A6" \
     -H "x-api-key: mn_your_key_here"

7. 07monitors/trendswired · unproven0 credits

   A metric over time with the previous period and the baseline beside it, so a change can be judged against what is normal for this monitor.

   curl

   curl "https://www.monocrawl.com/v1/monitors/trends?id=mon_%E2%80%A6&metric=findings&days=30" \
     -H "x-api-key: mn_your_key_here"

8. 08monitors/healthlive · proven0 credits

   A monitor's health and coverage: consecutive failures, missed checks, stale sources, provider failures, which configured sources are live, and what its checks cost and avoided.

   curl

   curl "https://www.monocrawl.com/v1/monitors/health?id=mon_%E2%80%A6" \
     -H "x-api-key: mn_your_key_here"

9. 09monitors/reportwired · unproven0 credits

   Turns a monitor's findings (or one story) into a saved research report with citations, verified facts kept apart from generated interpretation, ready to share or export as Markdown or JSON.

   curl

   curl "https://www.monocrawl.com/v1/monitors/report?id=mon_%E2%80%A6&days=7" \
     -H "x-api-key: mn_your_key_here"

10. 10monitors/runlive · proven0 credits for the call; the run itself is charged at its estimate

    Queue one run of a subject or feed monitor outside its schedule. The estimate is returned first; the run is charged at that estimate when you confirm, refunded down to what was actually retrieved, and skipped without a charge if the monthly cap would be exceeded.

    curl

    curl "https://www.monocrawl.com/v1/monitors/run?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a&confirm=true" \
      -H "x-api-key: mn_your_key_here"

11. 11monitors/updatelive · proven0 credits

    Pause, resume, rename, reschedule or re-scope one of your monitors. Give at least one field besides id.

    curl

    curl "https://www.monocrawl.com/v1/monitors/update?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a" \
      -H "x-api-key: mn_your_key_here"

12. 12monitors/deletelive · proven0 credits

    Permanently delete one of your monitors and its recorded run history, and cancel any check already queued for it. A Monocrawl extra: the reference catalogue catalogue has no monitor delete call, which makes its per-account monitor limit unrecoverable. This cannot be undone.

    curl

    curl "https://www.monocrawl.com/v1/monitors/delete?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a" \
      -H "x-api-key: mn_your_key_here"

13. 13monitors/proposewired · unproven0 credits

    Turns a plain-English request into a complete, editable monitor proposal: what it watches, the identifiers it found, the platforms, the matching rules and exclusions, the frequency, the delivery and the estimated cost, with the reason for each choice. Nothing is created.

    curl

    curl "https://www.monocrawl.com/v1/monitors/propose?text=Tell%20me%20when%20people%20complain%20about%20Monzo%20on%20Reddit%20or%20Hacker%20News" \
      -H "x-api-key: mn_your_key_here"

14. 14monitors/draftswired · unproven0 credits

    The proposals waiting for review. A draft is saved, edited, tested and finally activated into a monitor or discarded; nothing runs or is charged while it is a draft.

    curl

    curl "https://www.monocrawl.com/v1/monitors/drafts" \
      -H "x-api-key: mn_your_key_here"

15. 15monitors/feedbackwired · unproven0 credits

    Records your verdict on findings and remembers it: what you mark known, resolved or irrelevant is not surfaced again by later runs (the same conversation, link, wording, topic or, for irrelevant, author), and what you mark useful is kept as a positive example for the relevance filter.

    curl

    curl "https://www.monocrawl.com/v1/monitors/feedback?id=mon_%E2%80%A6&ids=fnd_%E2%80%A6%2Cfnd_%E2%80%A6&verdict=irrelevant" \
      -H "x-api-key: mn_your_key_here"

16. 16monitors/exportwired · unproven0 credits

    Every finding in the window with its receipts — source, quote, link, author, posted time, severity, matches, story, topic, your verdict and the raw evidence row it was made from — as CSV or JSON.

    curl

    curl "https://www.monocrawl.com/v1/monitors/export?id=mon_%E2%80%A6&format=json&days=30" \
      -H "x-api-key: mn_your_key_here"

17. 17monitors/indexlive · proven0 credits

    Your monitors, newest first, with each one's schedule and next due time.

    curl

    curl "https://www.monocrawl.com/v1/monitors/index" \
      -H "x-api-key: mn_your_key_here"

18. 18monitors/analyticswired · unproven0 credits

    Your monitoring at a glance: monitors by state, runs, findings, suppressed duplicates, alert delivery, credits, upstream cost and cache savings, and time to first finding.

    curl

    curl "https://www.monocrawl.com/v1/monitors/analytics" \
      -H "x-api-key: mn_your_key_here"

19. 19monitors/settingswired · unproven0 credits

    Read or change the account-wide monitor budget and the digest schedule. Reads with no parameters; writes with any of them.

    curl

    curl "https://www.monocrawl.com/v1/monitors/settings?digest_frequency=daily&digest_hour=8" \
      -H "x-api-key: mn_your_key_here"

Money

Credit estimation and monitor caps

A subject run is a Research briefing: it is charged at the briefing price when queued, then settled against the briefing’s retrieval charge. A failed subject check, or a result that cannot produce a briefing, is refunded in full. A successful briefing can still be charged when the monitor’s filters keep zero findings; filtering is not a refund condition. A feed run is charged for its successful endpoint reads, even when no new items are retained. The estimate you see before activation is price × runs per month, then limited by the monitor’s cap.

• Default cap 300 credits a month per monitor, maximum 5000; a cap of 0 prevents paid checks; it is not an unlimited setting.
• When a run would take the month past the cap, or the account cannot cover the estimate, the run is skipped and recorded — not charged by that skipped run. Opt-in account auto-recharge is a separate billing setting, not a promise that a capped monitor will restart immediately. The monitor shows why and resumes on the first of the next month (or when you raise the cap or top up).
• Refunds ride the ledger’s refund-once rule: a scheduler retry cannot refund, charge, record or notify twice.
• Monitor caps are additional budgets, not separate wallets. Scheduled runs spend the account balance; a per-key API cap is not a substitute for monitor and account-wide monitoring caps.

Time

Schedules

The scheduler ticks every few minutes and queues due runs. The console offers every 15 minutes, hourly, every 6 hours, once a day, weekly; the API accepts any interval from 15 minutes to 30 days. A late run never fires catch-up runs for the slots it missed — the next run is timed from now. Each subject run continues from the last successful run (with a small overlap so late replies still count); the first run looks back lookback_days (default 7).

Honesty

Partial source failures and receipts

Every run keeps a receipt per platform: status, whether it was served by the primary route, a fallback or the cache, and how many items it found and kept. A platform that fails is named as failed and not charged; when every platform fails the monitor asks for attention. Receipts name platforms — which upstream served a platform is operator information and never appears in customer output.

A check never mistakes a cached answer for a fresh look: a monitor accepts a shared cached answer only if it is younger than the monitor’s own interval, so nothing older than your previous check can be reported as “unchanged”. Older answers trigger retrieval. Cache reuse and concurrent-request coalescing can share eligible public data, but are best-effort and do not guarantee one upstream call across all monitors.

Findings

What counts, and duplicate suppression

A subject run is a briefing continued from the last one, so it inherits Research’s rules: conversations rather than keyword hits, material that is about the subject (not a namesake), owned material kept apart from audience reaction, dates treated honestly, absolute counts and unique authors, no percentages from tiny samples, and generated claims linked to supporting evidence. Automated interpretation can be wrong; inspect the cited records.

• Findings are deduplicated within each monitor, keyed by the evidence’s canonical id; a post seen again on a later run, or the same story cross-posted, is not a new finding.
• Relationships: audience reaction, editorial and news, official and owned, employees and team, collaborators and partners, fan and clip accounts. Unrelated material is always left out.
• Purpose filters are phrase matches and say what they matched: complaints (complaints and negative feedback); switching (customers considering an alternative); buying (purchase or recommendation intent); bugs_crashes (crashes, freezes and errors); bugs_glitches (glitches and things that look wrong); bugs_exploits (exploits, cheats and duplication); bugs_blockers (stuck, blocked or lost progress); bugs_performance (lag and performance); requests (requests, suggestions and feedback); questions (questions the subject could answer).
• Feed monitors baseline on the first run — existing items are recorded as already seen — and report only new items afterwards.
• Findings you have reviewed are marked seen (mark_seen=true); the monitor keeps “new since your review” separate from “recorded”.
• A verdict (monitors/feedback: known, resolved, irrelevant, useful) is remembered as signatures of the finding; later candidates that match are held back before anything judges them, and the run summary lists them under held_by_memory with the reason.
• Each finding carries evidence.record, a bounded copy of the row it was made from subject to the storage limits above, and why, the deterministic reasons it matched; topic_key groups the same discussion across platforms and runs.

Alerts

Webhook events and signature verification

Three events are emitted for monitors: monitor.findings when a run records something new, monitor.digest when a digest is sent, and monitor.attention when a subject becomes ambiguous or a monitor pauses itself after repeated failures. Delivery follows the monitor’s chosen destinations and cadence; account-level or legacy events use subscribed endpoints. JSON deliveries are signed and retried. Payload fields differ by event—findings, digests and attention notices do not all have the same shape.

import crypto from 'node:crypto';

// rawBody is the original Buffer (or unmodified UTF-8 string), BEFORE JSON parsing.
export function verifyMonocrawlSignature(rawBody, header, secret, nowMs = Date.now()) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');
  if (!match || !secret) return false;
  const [, timestamp, signature] = match;
  const seconds = Number(timestamp);
  if (!Number.isSafeInteger(seconds) || Math.abs(nowMs / 1000 - seconds) > 300) return false;
  const expected = crypto.createHmac('sha256', secret)
    .update(timestamp + '.').update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');
  return received.length === expected.length && crypto.timingSafeEqual(expected, received);
}

Events you can subscribe to: billing.low_balance, billing.credits_exhausted, billing.purchase_succeeded, billing.auto_recharge.succeeded, billing.auto_recharge.failed, subscription.renewed, subscription.ended, job.completed, job.failed, monitor.findings, monitor.attention, monitor.digest. Deliveries are at-least-once — dedupe on the delivery id.

Operations

Pausing, resuming and deleting

Pause clears the next run; resume schedules one interval from now; deleting removes the monitor, its runs and its findings and cancels any queued run. Run now quotes the cost first and only charges when you confirm. Name, schedule, cap and delivery can be edited. Subject and feed monitors also support sources, relationships, filters and exclusions through monitors/update. To follow a different subject or target, create a new monitor; check the endpoint’s parameter table for supported changes.

Presets

What each preset watches

Availability is decided per deployment from live-proven evidence; the console shows a preset as not offered when its required proof is missing; presets with alternative feeds may be offered with only the proven feeds enabled.