Monitors API

    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.

    text
    schedule ──▶ run ──▶ retrieve ──▶ dedupe (seen) ──▶ AI screen ──▶ items ──▶ webhook

    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?

    GoalUseNot this
    New posts, pages, and videos about a topic, every hour or day, without repeatsMonitors (this page)Calling Search on a cron and deduping yourself
    One answer or one set of results nowSearch API or AI SearchA monitor with run_now
    Every new post from a few accounts, on a scheduleMonitors with watched accounts (below) and min_score: 0Polling each account's feed yourself
    New TikTok or Instagram posts with a hashtag, from any accountMonitors with watched hashtags (below)Polling the hashtag feed yourself
    New Meta ads for a brand or product, on a scheduleMonitors with meta_ads and a keyword query (see Meta ads below)Polling POST /desearch/facebook/search yourself
    One read of an account's posts nowX API or Social APIsA monitor
    Fresh metrics for a post a monitor foundGET /desearch/social/post with the item's urlRunning the monitor again
    A list of people or companies that match a descriptionPeople Search or Company SearchMonitors

    Base URL: https://api.desearch.ai
    Auth: Authorization: $DESEARCH_API_KEY (raw key in examples).

    First call: create a monitor

    bash
    curl --request POST 'https://api.desearch.ai/desearch/monitors' \ --header "Authorization: $DESEARCH_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "name": "Bittensor subnet news", "query": "Bittensor subnet launches and updates", "criteria": ["Announces a new subnet, release or partnership"], "sources": ["web", "x", "reddit", "youtube"], "interval": "1d", "webhook": {"url": "https://example.com/hooks/desearch"} }'

    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:

    FieldMeaning
    queryRequired. What to watch, in plain words. Each source is searched with it. 3 to 500 characters.
    nameA label for the monitor. Up to 120 characters.
    criteriaUp 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.
    sourcesAny 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).
    intervalHow often it runs: 1h, 3h, 6h, 12h, 1d, or 7d. Default 1d.
    optionsPer-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_scoreThe relevance score (0 to 100) an item needs to be kept. Default 60.
    summaryDefault 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.
    metadataYour own labels, for example {"team": "growth"}.
    run_nowDefault 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.

    OptionAccounts
    x.accountsX usernames: NASA, @NASA, or https://x.com/NASA
    reddit.subredditsLocalLLaMA, r/LocalLLaMA, or a subreddit URL
    tiktok.accountsTikTok usernames: nasa, @nasa, or a profile URL
    threads.accountsThreads usernames: nasa, @nasa, or a profile URL
    instagram.accountsInstagram 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.pagesFacebook 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.

    bash
    curl --request POST 'https://api.desearch.ai/desearch/monitors' \ --header "Authorization: $DESEARCH_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "name": "NASA announcements", "query": "NASA mission and launch announcements", "sources": ["x", "tiktok"], "interval": "6h", "min_score": 0, "options": { "x": {"accounts": ["NASA", "@NASAWebb"]}, "tiktok": {"accounts": ["nasa"], "count": 10} } }'

    Instagram profiles, Facebook pages, and Threads profiles work the same way:

    bash
    curl --request POST 'https://api.desearch.ai/desearch/monitors' \ --header "Authorization: $DESEARCH_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "name": "NASA posts", "query": "NASA missions and launches", "sources": ["instagram", "facebook", "threads"], "interval": "12h", "min_score": 0, "options": { "instagram": {"accounts": ["nasa"]}, "facebook": {"pages": ["NASA"]}, "threads": {"accounts": ["nasa"]} } }'

    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.

    OptionHashtags
    tiktok.hashtagsskincare, #სილამაზე, or a tag URL such as https://www.tiktok.com/tag/skincare
    instagram.hashtagsskincare, #სილამაზე, 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.

    bash
    curl --request POST 'https://api.desearch.ai/desearch/monitors' \ --header "Authorization: $DESEARCH_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "name": "Skincare brand mentions", "query": "Posts about our skincare brand", "sources": ["tiktok", "instagram"], "interval": "6h", "min_score": 0, "options": { "tiktok": {"hashtags": ["#სილამაზე", "https://www.tiktok.com/tag/skincare"], "count": 10}, "instagram": {"hashtags": ["skincare", "სილამაზე"]} } }'

    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 same query, so give meta_ads a keyword query.
    • Screening. Ads are screened with their own relevant question and no new_info, so a Meta ad item's signals has no new_info.
    bash
    curl --request POST 'https://api.desearch.ai/desearch/monitors' \ --header "Authorization: $DESEARCH_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "name": "Running shoe ads", "query": "running shoes", "sources": ["meta_ads"], "interval": "1d", "options": {"meta_ads": {"count": 20}} }'

    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.

    bash
    curl --request POST 'https://api.desearch.ai/desearch/monitors/estimate' \ --header "Authorization: $DESEARCH_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"sources": ["web", "x", "reddit", "youtube"], "interval": "1d"}'
    json
    { "max_run_cost_usd": 0.01414, "runs_per_month": 30, "max_monthly_cost_usd": 0.4242, "breakdown": { "x": 0.003, "web": 0.003, "reddit": 0.00207, "youtube": 0.00207, "screening": 0.004 } }

    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.

    bash
    curl --get 'https://api.desearch.ai/desearch/monitors/6f1d0c9e-0d55-4b8e-9a3c-3c4d9b8e2a10/items' \ --header "Authorization: $DESEARCH_API_KEY" \ --data-urlencode 'source=x' \ --data-urlencode 'limit=50'

    Item

    FieldMeaning
    scoreThe relevance score, 0 to 100: the lowest of relevant and each criterion, times 100.
    signalsThe 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_atWhen the source published the item. found_at is when the monitor kept it.
    dataSource 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:

    FieldMeaning
    post_idThe post's ID, the one GET /desearch/social/post gives the same post. On Instagram it is the shortcode.
    typevideo, image, carousel, reel, and so on, as GET /desearch/social/post names it.
    hashtagsThe post's hashtags, without #.
    mentionsAccounts the post mentions (TikTok and Instagram).
    mediaLinks to the post's videos and pictures.
    thumbnailThe 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.

    FieldMeaning
    triggerschedule, or manual (a trigger call, or the first run queued on create).
    statusqueued, running, completed, failed, or cancelled.
    fail_reasonnull, or why the run failed.
    stats.sourcesPer 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.screenai when the AI classifier screened the items.
    reserved_usd, cost_usdWhat the run held on your balance and what it was billed.

    Change, pause, or delete a monitor

    CallWhat happens
    GET /desearch/monitorsYour 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.

    bash
    curl --request PATCH 'https://api.desearch.ai/desearch/monitors/6f1d0c9e-0d55-4b8e-9a3c-3c4d9b8e2a10' \ --header "Authorization: $DESEARCH_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"status": "paused"}'

    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.

    EventWhen
    monitor.items.foundA run kept at least one item. On by default.
    monitor.run.completedEvery completed run, with or without items.
    monitor.run.failedA run failed. On by default.
    monitor.testOnly 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:

    FieldMeaning
    consecutive_failuresDeliveries in a row that failed.
    last_deliveryThe newest delivery, or null before the first.
    last_delivery.statuspending, delivered, or failed.
    last_delivery.attemptsAttempts so far.
    last_delivery.status_code, errorYour endpoint's last answer.
    last_delivery.created_at, next_attempt_at, delivered_atWhen 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: true adds 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 shows reserved_usd and cost_usd.
    • When your balance runs out, the monitor pauses with paused_reason: "insufficient_credits" until you set status: "active" again.
    • stats.spent_usd on 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:

    SourceEach run pays
    x.accountsThe X posts it reads, at the X list price
    reddit.subreddits, threads.accountsOne request each, at that route's list price
    tiktokOne read per watched account or hashtag, or one for the keyword search: $0.003 each (the hold counts two reads per account)
    instagramOne read per watched account or hashtag: $0.003 each
    facebookOne read per watched page: $0.003 each
    meta_adsOne read per run, $0.003, whatever meta_ads.count

    Rates are on the pricing page.

    Errors

    StatusMeaning
    400A 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.
    401Missing API key, or a key that is not valid.
    402Your balance cannot hold one run of this monitor, on create or on a trigger.
    403A malformed Authorization value, such as an unreplaced placeholder like YOUR_API_KEY. See Auth and API keys.
    404Monitor or run not found.
    409too_many_monitors, or on a trigger while a run is queued or running (detail: This monitor is already running.).
    422A 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.

    Related