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

Optional filtering

Only tell me if it’s actually relevant

Describe the meaning you want an alert to have, including required conditions and anything to leave out. Monocrawl checks collected results after existing exclusions and duplicate checks. You do not need to choose an intent category or supply an AI key.

Numeric AI criteria — beta. Filters that compare numbers, thresholds or percentage changes can still produce incorrect matches. Check the saved source evidence and calculation before acting on a numeric alert.

• Recommendation requests: “Someone asking for a sea salt spray recommendation for their own hair. Exclude discounts, affiliate promotions and casual mentions.”
• Security monitoring: “Substantive reports of PostgreSQL security vulnerabilities or released security fixes. Exclude hiring adverts and course promotions.”
• Reviews: “A reviewer describing repeated charging or battery failures after using the product. Exclude speculation from people who have not used it.”

Write alternatives with “or” and required combinations with “and”. Require a location, date or first-hand account only if it matters to you. If the collected content does not establish a required fact, the result can remain undecided. Put meaning-based exclusions in the description; literal exclusion phrases can also remove a useful post that quotes those words.

When interpretation or a response fails validation, a fallback model can be used within the existing limits. Processing errors follow bounded retries using saved content. Genuinely insufficient evidence stays undecided without repeatedly paying to judge unchanged information. Relevant changes to content, context, criteria or classifier version can trigger reassessment while the monitor is active. Errors are not silently treated as irrelevant.

In Runs or Check history and costs, look for Check complete with undecided items, Relevance processing pending or Filtering incomplete. Through monitors/runs, inspect processing_status and summary.filtering, including unjudged, undecided, retry and note. A completed collection or delivered match does not mean every item was judged.

Decisions are reused only for matching content, context, criteria and classifier version. Changing criteria does not rewrite old alerts or promise a full historical rescan. Turning the filter off retains saved criteria and leaves other monitor rules and exclusions in place. Filtering uses already collected content; opening results or evidence makes no additional model call or supplier request. Scheduled checks still use the displayed estimate and existing spending limits, including when no item matches.

Automated interpretation can miss a match or accept an unwanted item. Supporting passages show why content was selected; they do not independently verify a source’s claim. Review early results and refine the description.

API setup

Create, inspect or change a relevance filter

Use the existing monitors/create and monitors/update parameters. They apply to every monitor kind. monitors/get and the monitor list at GET /v1/monitors return saved relevance settings and exclusions.

On update, omit settings you want to retain. Review the subject and current estimate with monitors/preview before creating a monitor. The REST create call below executes immediately and incurs the current creation charge; scheduled checks then use your available credits. The key and criteria below are illustrative.

curl --get 'https://www.monocrawl.com/v1/monitors/create' \
  -H 'x-api-key: mn_your_key_here' \
  --data-urlencode 'kind=subject' \
  --data-urlencode 'query=PostgreSQL' \
  --data-urlencode 'sources=hackernews' \
  --data-urlencode 'schedule_minutes=1440' \
  --data-urlencode 'relevance_enabled=true' \
  --data-urlencode 'relevance_prompt=Substantive reports of PostgreSQL security vulnerabilities or released security fixes. Exclude hiring adverts and course promotions.' \
  --data-urlencode 'exclusions=discount code,affiliate link'

Use the returned monitor id for reads and updates. This example disables only the relevance filter; it does not pause the monitor:

curl --get 'https://www.monocrawl.com/v1/monitors/update' \
  -H 'x-api-key: mn_your_key_here' \
  --data-urlencode 'id=mon_your_monitor_id' \
  --data-urlencode 'relevance_enabled=false'

Read retained findings with monitors/findings?id=…&limit=50. Pass each returned data.cursor as cursor until it is null to read beyond the first page. Findings include url, text, why and stored evidence. For filtered findings, matched.relevance holds the saved explanation and matched.relevance_decision.evidence holds selected passages. Read monitors/runs for undecided counts and processing status; those items are not confirmed findings. Reading findings does not itself send alerts.

For Claude or another connected agent, use the dedicated monitor tools and the MCP filtering example. You can inspect or edit that same monitor in the dashboard afterwards.

Alerts and results

Open an alert, inspect the match, visit the source

A relevance-filtered monitor opens Matching results by default. On the monitor list, selecting it opens the existing Results tab. A delivered alert links to its saved finding, highlighted as Selected alert, with useful collected text, Why it matched, a supporting passage and Visit source. Identical title and body text are not repeated as a second body.

The explanation and passages were saved during filtering. Viewing them does not ask AI to write a new explanation. A source may only supply a headline or excerpt; the displayed evidence is limited to what was collected. Follow Visit source to open the original post or its discussion. A separate linked page is shown where available.

The monitor list shows unread alerts. The Alerts inbox includes read and unread deliveries, the total unread count and Older alerts/Newer alerts pagination. Opening an exact finding marks its corresponding dashboard alert read; Mark all read marks the inbox read. Read alerts remain accessible. Findings have separate result pagination, and All matching results leaves an individual alert view.

Clearly equivalent article coverage appears as one story, with additional findings expandable to their own evidence and source links. Repeated coverage can be held from another notification during the cooldown, while substantive new developments or escalation can alert separately. Stories are not grouped merely because they mention the same company. Grouping is conservative and can miss paraphrases; it preserves the underlying findings. Historical duplicate alerts remain part of delivery history.

Stored data

Raw collection history: Table and Reading views

Choose Raw collection history on the full monitor to inspect collected records, including excluded and undecided items. These are not all matching alerts. Table and Reading views show the same stored records, with search, source and date filters; 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; relevance-filtered monitors default to matching results, with raw records kept in this separate view.

Builder

Say it in a sentence, review the whole monitor

Use the existing monitor setup, or ask a connected agent for a proposed watch. “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 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 saved output and notifications. Relevance-filtered monitors open matching results; raw history remains separately accessible. 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; these report diagnostics are separate from the matching-results and raw-history views. 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.

Published fields can be optional. Confirm a preview to check the actual source values before scheduling. A zero is a valid observation; a missing, null, string or boolean value is not. If any selected metric is unavailable in a preview or run, no numeric observation or change is recorded and the customer charge is refunded. Runs retain the source cost receipt and metric status. A nonnumeric value pauses the monitor for review; missing values use the existing retry and pause rules. Recorded metric keys keep their full pointer, such as /followers, for monitors/timeseries and monitors/trends.

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 can grow one developing story. Equivalent article coverage is grouped conservatively by the event, not merely a shared company name; every finding and source is retained. Repeated coverage within the cooldown can be held from another alert, while substantive developments or escalation can alert separately. Other monitor kinds retain their existing rule, conversation and review-source grouping. 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; relevance-filtered monitors open matching results in the console.
• 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, missed checks, recent errors, source coverage and delivery status. monitors/analytics gives the account view: checks, findings, alert delivery, credits used, checks served from cache 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.
• The available balance is checked before a run is charged. If it cannot fund a check, the monitor pauses and resumes automatically once sufficient credits are available. Monthly monitoring caps are no longer enforced.
• 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, 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 new findings; a feed monitor records new items from a review or listing endpoint; a change monitor snapshots a page or endpoint. Creating costs the listed credits. Each run reserves its quoted credits before starting; unused reserved credits are refunded. Runs pause if available account funding cannot cover the next check. No monthly monitor cap applies.

   curl

   curl "https://www.monocrawl.com/v1/monitors/create?kind=subject&query=Monzo&purpose=complaints&schedule_minutes=360" \
     -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/trendslive · proven0 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: recent successful and failed checks, missed checks, stale sources, available coverage, delivery status and checks served from cache.

   curl

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

9. 09monitors/reportlive · proven0 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 monitor check outside its schedule. Review the estimate before confirming. The run reserves its quoted credits, settles the actual charge within that quote and refunds unused credits. If available account funding cannot cover the estimate, no job is started and no credits are charged. No monthly monitor cap applies.

    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&confirm=true" \
      -H "x-api-key: mn_your_key_here"

13. 13monitors/proposelive · proven0 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/draftslive · proven0 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/feedbacklive · proven0 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/exportlive · proven0 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/analyticslive · proven0 credits

    Your monitoring at a glance: monitors by state, completed and pending checks, findings, alert delivery, credits used, checks served from cache and time to the first finding.

    curl

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

19. 19monitors/settingslive · proven0 credits

    Read or change the monitoring digest schedule and delivery preferences. Reads with no parameters; writes with any supported setting. The legacy monthly_budget_credits field is ignored; account billing limits still apply.

    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 estimates and available balance

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. Monthly monitor and account monitoring caps do not apply.

• No monthly monitor or account monitoring spending limit applies. Legacy monthly_cap_credits and monthly_budget_credits inputs are accepted for compatibility but ignored; responses report null.
• If the account cannot cover the estimate, the run is skipped and recorded without a charge. Your subscription allowance still resets on your billing date. To keep scheduled checks running, add extra credits or turn on auto-reload in Billing.
• Auto-reload adds purchased credits only after payment succeeds. Payment failures and open card disputes pause it until resolved.
• Refunds ride the ledger’s refund-once rule: a scheduler retry cannot refund, charge, record or notify twice.
• All sources use the account balance without a fixed monthly split. Each check reserves its quote atomically; unused credits are returned on settlement. A source can consume the remaining balance, leaving others paused until they can be funded.

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 is not a new finding. Separate posts covering the same event can remain separate findings inside one story, preserving each source while avoiding redundant notifications where grouping establishes equivalent coverage.
• 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; story_id identifies its story group, while topic_key retains topic context.

Alerts

Webhook events and signature verification

Use the monitor payload reference for field tables and the two digest shapes, and the working receiver example for verification, deduplication and durable receipt.

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 and delivery can be edited. Every monitor supports the optional relevance_enabled, relevance_prompt and exclusions settings through monitors/update. Subject and feed monitors also support sources, relationships and filters. 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.