Monitors API
A monitor is a search that runs on a schedule and returns only what is new since its last run. Describe what to watch in plain language, for example "Bittensor subnet launches and updates", pick the sources (web, X, Reddit, YouTube, Threads, TikTok, Instagram, Facebook, Meta ads) and how often it runs (every hour to every 7 days). A source can also watch up to 10 accounts, such as X users, subreddits, TikTok, Threads, or Instagram creators, or Facebook pages, instead of searching, and TikTok and Instagram can watch up to 10 hashtags each, which find posts from any account; Instagram and Facebook only watch accounts (and Instagram hashtags). Each run drops everything the monitor has already seen and screens the rest for relevance with AI. The items that pass go to your webhook and stay readable through the API.
Who this page is for
Humans
Create a monitor with one POST, then read the items it keeps, or let it push them to your webhook. Creating, reading, and changing monitors is free. Each run pays for the searches it makes, at their list price, plus a small screening fee per new item. Full schemas are in the API Reference.
Agents / tool authors
A monitor runs in the background. POST /desearch/monitors returns the monitor at once, and with run_now (the default) its first run is already queued. Read new items with GET /desearch/monitors/{monitor_id}/items and the next_cursor it returns, or receive them as monitor.items.found webhook events. An item is delivered once per monitor: a later run never returns it again. Use POST /desearch/monitors/estimate before creating a monitor to show the most a run and a month can cost.
Which surface should I use?
| Goal | Use | Not this |
|---|---|---|
| New posts, pages, and videos about a topic, every hour or day, without repeats | Monitors (this page) | Calling Search on a cron and deduping yourself |
| One answer or one set of results now | Search API or AI Search | A monitor with run_now |
| Every new post from a few accounts, on a schedule | Monitors with watched accounts (below) and min_score: 0 | Polling each account's feed yourself |
| New TikTok or Instagram posts with a hashtag, from any account | Monitors with watched hashtags (below) | Polling the hashtag feed yourself |
| New Meta ads for a brand or product, on a schedule | Monitors with meta_ads and a keyword query (see Meta ads below) | Polling POST /desearch/facebook/search yourself |
| One read of an account's posts now | X API or Social APIs | A monitor |
| Fresh metrics for a post a monitor found | GET /desearch/social/post with the item's url | Running the monitor again |
| A list of people or companies that match a description | People Search or Company Search | Monitors |
Base URL: https://api.desearch.ai
Auth: Authorization: $DESEARCH_API_KEY (raw key in examples).
First call: create a monitor
The response is 201 Created with the new monitor. max_run_cost_usd is the most one run can cost. With a webhook, the response also carries webhook_secret (whsec_…), and only this once: store it with your webhook handler.
Request body fields:
| Field | Meaning |
|---|---|
query | Required. What to watch, in plain words. Each source is searched with it. 3 to 500 characters. |
name | A label for the monitor. Up to 120 characters. |
criteria | Up to 5 conditions an item must meet to be kept, each up to 300 characters, for example "Announces a new subnet, release or partnership". The AI screen checks each one. |
sources | Any of web, x, reddit, youtube, threads, tiktok, instagram, facebook, meta_ads. At least one. instagram needs watched accounts or hashtags and facebook watched pages (see below). |
interval | How often it runs: 1h, 3h, 6h, 12h, 1d, or 7d. Default 1d. |
options | Per-source settings: web.count (10, 15, or 20 pages per run, default 10); x.count (1 to 100 newest posts per run, default 20), x.lang (for example en), x.min_likes, and x.accounts; reddit.subreddits; threads.accounts; tiktok.count (10, 20, or 30 posts per run, default 10), tiktok.accounts, and tiktok.hashtags; instagram.accounts and instagram.hashtags (one of them required with instagram); facebook.pages (required with facebook); meta_ads.count (10, 20, or 30 ads per run, default 10). See Watched accounts, Watched hashtags, and Meta ads below. |
min_score | The relevance score (0 to 100) an item needs to be kept. Default 60. |
summary | Default false. When true, an LLM writes a short digest of the items each run keeps, in the run's summary. |
webhook | {"url": "https://…", "events": [...]}: where to send new items. See Webhooks below. |
metadata | Your own labels, for example {"team": "growth"}. |
run_now | Default true: the first run is queued at once. Send false to wait for the first scheduled run. |
The body accepts only these fields, and each source's options accept only their own keys. An unknown field or key fails validation with 422.
How a run works
Each run reads its sources, drops what the monitor has already seen, and screens the rest. An item an earlier run saw is not screened or delivered again.
Watched accounts
A source can watch up to 10 accounts instead of searching by keyword. Each run then reads every account's newest posts, and the query and criteria still decide what is kept, as with search results. Set min_score: 0 to keep every new post.
| Option | Accounts |
|---|---|
x.accounts | X usernames: NASA, @NASA, or https://x.com/NASA |
reddit.subreddits | LocalLLaMA, r/LocalLLaMA, or a subreddit URL |
tiktok.accounts | TikTok usernames: nasa, @nasa, or a profile URL |
threads.accounts | Threads usernames: nasa, @nasa, or a profile URL |
instagram.accounts | Instagram usernames: nasa, @nasa, or a profile URL. instagram needs these or instagram.hashtags. Each run reads up to 12 newest posts from each profile. |
facebook.pages | Facebook page names or numeric IDs: NASA, 100064869009429, or a page URL. Required with facebook. |
Names are cleaned and returned that way: @NASA or https://x.com/NASA becomes NASA, r/LocalLLaMA becomes LocalLLaMA, an Instagram or Threads profile URL becomes the username (1 to 30 of A-Z, a-z, 0-9, ., and _), and a Facebook page URL becomes its name or numeric ID (profile.php?id=… and /pages/Name/123… become the ID). More than 10 accounts on one source, or a name that is not valid for it, fails with 422.
Instagram and Facebook have no keyword search for posts, so those sources only watch accounts (Instagram also hashtags, see below). A monitor with instagram in sources needs at least one name in options.instagram.accounts or one hashtag in options.instagram.hashtags, and one with facebook at least one page in options.facebook.pages. Create returns 422 without one, and detail names the options, for example Instagram watches accounts or hashtags: add at least one in options.instagram.accounts or options.instagram.hashtags. POST /desearch/monitors/estimate does not check this. For ads by keyword, use meta_ads.
Instagram profiles, Facebook pages, and Threads profiles work the same way:
An item read from a watched account has data.account, the name it was watched as. An account that cannot be read is listed in the run's stats.sources.<source>.accounts_failed.
Watched hashtags
TikTok and Instagram can also watch up to 10 hashtags each, in any script: options.tiktok.hashtags and options.instagram.hashtags. A hashtag feed lists posts from any account, so a monitor finds posts outside the accounts it watches, and the query and criteria still decide what is kept. With accounts or hashtags, a source reads those feeds instead of searching by keyword. Instagram can watch hashtags without accounts.
| Option | Hashtags |
|---|---|
tiktok.hashtags | skincare, #სილამაზე, or a tag URL such as https://www.tiktok.com/tag/skincare |
instagram.hashtags | skincare, #სილამაზე, or a tag URL such as https://www.instagram.com/explore/tags/skincare/ |
A hashtag is kept without its # (a tag URL becomes its tag), in any script, and returned that way. More than 10 hashtags on one source, or one that is not a hashtag (two words, or a post URL), fails with 422. Facebook has no organic hashtag feed: for ads by keyword, use meta_ads.
An item read from a hashtag has data.hashtag, the tag it was read from. A hashtag that cannot be read is listed in the run's stats.sources.<source>.hashtags_failed.
Meta ads
meta_ads searches the Meta Ad Library by keyword. options.meta_ads.count is how many ads a run reads: 10, 20, or 30 (default 10).
- Use keywords. The Ad Library matches keywords, so the query should be a product, a brand, or a short phrase, such as
running shoes. Every source in a monitor uses the samequery, so givemeta_adsa keyword query. - Screening. Ads are screened with their own
relevantquestion and nonew_info, so a Meta ad item'ssignalshas nonew_info.
Estimate the cost
POST /desearch/monitors/estimate takes sources, options, summary, and interval, and returns the most one run and one month can cost. It is free.
breakdown is the most each part of a run can cost: each source's search or watched accounts, screening, and summary when it is on. A run usually costs less, because it pays only for the items it screens.
Read the items
GET /desearch/monitors/{monitor_id}/items returns everything the monitor kept, newest first. Pass source to read one source, limit (1 to 200, default 50), and the next_cursor from the previous page as cursor. next_cursor is null on the last page.
Item
| Field | Meaning |
|---|---|
score | The relevance score, 0 to 100: the lowest of relevant and each criterion, times 100. |
signals | The AI screen's answers, 0 to 1: relevant and new_info, plus criteria (the lowest answer across the criteria) when the monitor has criteria. A Meta ad has no new_info. |
published_at | When the source published the item. found_at is when the monitor kept it. |
data | Source fields. X: likes, reposts, replies, views. TikTok: views, likes, comments, shares, saves, duration_s. Threads: likes. Instagram: likes, comments, views, media_type. Facebook: reactions, comments, shares. Meta ads: page, active, cta, link (the ad's landing page), platforms. Web: highlights, domain. TikTok, Instagram, and Facebook items also have the post fields below. An item from a watched account also has account, and one from a watched hashtag hashtag. |
TikTok, Instagram, and Facebook items also carry the post's own fields in data:
| Field | Meaning |
|---|---|
post_id | The post's ID, the one GET /desearch/social/post gives the same post. On Instagram it is the shortcode. |
type | video, image, carousel, reel, and so on, as GET /desearch/social/post names it. |
hashtags | The post's hashtags, without #. |
mentions | Accounts the post mentions (TikTok and Instagram). |
media | Links to the post's videos and pictures. |
thumbnail | The cover image. |
The metrics (views, likes, and so on) are the post's when the run found it. To read them again later, call GET /desearch/social/post?url=<the item's url>; author=true adds the author's followers.
Runs
GET /desearch/monitors/{monitor_id}/runs lists runs newest first (limit 1 to 100, default 20, and cursor). GET /desearch/monitors/{monitor_id}/runs/{run_id} returns one run with the items it kept, most relevant first. POST /desearch/monitors/{monitor_id}/trigger queues a run now and returns it with 202, also on a paused monitor.
| Field | Meaning |
|---|---|
trigger | schedule, or manual (a trigger call, or the first run queued on create). |
status | queued, running, completed, failed, or cancelled. |
fail_reason | null, or why the run failed. |
stats.sources | Per source: items fetched, in the window, new to this monitor, and kept, with the source's error when its search failed, and accounts_failed and hashtags_failed (the watched accounts and hashtags that could not be read). |
stats.screen | ai when the AI classifier screened the items. |
reserved_usd, cost_usd | What the run held on your balance and what it was billed. |
Change, pause, or delete a monitor
| Call | What happens |
|---|---|
GET /desearch/monitors | Your monitors, newest first. Filter with status (active, paused, or both, comma-separated), page with limit (1 to 100, default 20) and cursor. |
GET /desearch/monitors/{monitor_id} | One monitor's settings, status, last run, totals (stats.runs, stats.items, stats.spent_usd), and next_run_at. |
PATCH /desearch/monitors/{monitor_id} | Change any create field (all optional). status: "paused" stops scheduled runs, and status: "active" resumes them. webhook: null removes the webhook. |
DELETE /desearch/monitors/{monitor_id} | Deletes the monitor; later calls on it return 404. Returns {"monitor_id": "…", "deleted": true}. |
paused_reason says why a monitor is paused: user, insufficient_credits, or webhook_failing. It is null while the monitor is active.
Webhooks
Set webhook on create or with PATCH to receive events. The URL must be HTTPS on a public address, and redirects are not followed.
| Event | When |
|---|---|
monitor.items.found | A run kept at least one item. On by default. |
monitor.run.completed | Every completed run, with or without items. |
monitor.run.failed | A run failed. On by default. |
monitor.test | Only from POST /desearch/monitors/{monitor_id}/webhook/test, whatever events lists. |
Each delivery carries a Desearch-Signature header. Verify it with the monitor's webhook_secret.
POST /desearch/monitors/{monitor_id}/webhook/test sends a monitor.test event and returns what your endpoint answered, for example {"delivered": false, "status_code": 405, "error": "HTTP 405", "duration_ms": 52} when your endpoint answers 405. Use it to check your endpoint before a run. POST /desearch/monitors/{monitor_id}/webhook/rotate-secret returns a new webhook_secret, once.
Delivery status
The monitor's webhook (null when it has none) shows how deliveries are going:
| Field | Meaning |
|---|---|
consecutive_failures | Deliveries in a row that failed. |
last_delivery | The newest delivery, or null before the first. |
last_delivery.status | pending, delivered, or failed. |
last_delivery.attempts | Attempts so far. |
last_delivery.status_code, error | Your endpoint's last answer. |
last_delivery.created_at, next_attempt_at, delivered_at | When the delivery was created, when the next attempt is due, and when your endpoint accepted it. |
Billing
- Creating, reading, changing, and deleting monitors is free, and so are the estimate, test, and rotate-secret calls.
- Each run pays for what it uses: its searches at their list price (the same price as calling those endpoints yourself) and AI screening at $0.05 per 1,000 items screened.
summary: trueadds to the cost of each run. Items the monitor has seen before are not screened again. - When a run is queued, its maximum cost (
max_run_cost_usd) is held on your balance. When it ends, it is billed what it used, never more than the hold, and the rest is released. The run showsreserved_usdandcost_usd. - When your balance runs out, the monitor pauses with
paused_reason: "insufficient_credits"until you setstatus: "active"again. stats.spent_usdon the monitor is the total its runs were billed.
TikTok, Instagram, Facebook, and Meta ads are billed per read, at $3.00 per 1,000 reads ($0.003 a read), whatever the number of posts a read returns. One read is one watched account, one hashtag, one Facebook page, one TikTok keyword search, or one Ad Library search (meta_ads, whatever meta_ads.count). A run's hold counts two reads per TikTok account. The other sources pay their feed's list price. The estimate includes them all:
| Source | Each run pays |
|---|---|
x.accounts | The X posts it reads, at the X list price |
reddit.subreddits, threads.accounts | One request each, at that route's list price |
tiktok | One read per watched account or hashtag, or one for the keyword search: $0.003 each (the hold counts two reads per account) |
instagram | One read per watched account or hashtag: $0.003 each |
facebook | One read per watched page: $0.003 each |
meta_ads | One read per run, $0.003, whatever meta_ads.count |
Rates are on the pricing page.
Errors
| Status | Meaning |
|---|---|
400 | A value the schema cannot catch: a webhook URL that is not HTTPS on a public address, an unknown status or source filter, an invalid cursor, or a test or rotate-secret call on a monitor with no webhook. |
401 | Missing API key, or a key that is not valid. |
402 | Your balance cannot hold one run of this monitor, on create or on a trigger. |
403 | A malformed Authorization value, such as an unreplaced placeholder like YOUR_API_KEY. See Auth and API keys. |
404 | Monitor or run not found. |
409 | too_many_monitors, or on a trigger while a run is queued or running (detail: This monitor is already running.). |
422 | A field is invalid, and detail lists each one: for example a query under 3 characters, an unknown source or interval, more than 5 criteria, min_score outside 0 to 100, more than 10 watched accounts or hashtags on a source or a name or hashtag that is not valid for it, instagram in sources without accounts or hashtags or facebook without pages, or an unknown field or option key. |