Monitors API — watch a source, get only what is new — FetchLayer Docs

Monitors API

A monitor watches a source on a schedule and hands you only what is new: a hashtag's new videos, new posts matching a keyword, an account's new posts, new reviews of an app. Each item reaches you once. Nothing runs on your side.

Authentication

Use the same API key as every other call, as Authorization: Bearer <key> or x-api-key: <key>. A key limited to some platforms can only set up monitors on those platforms. Monitors are on https://api.fetchlayer.dev/monitors. Each key may make 120 monitor requests a minute.

bash
curl https://api.fetchlayer.dev/monitors \
  -H "Authorization: Bearer ss-your-key"

Create a monitor

POST /monitors. Fields:

  • sources: what to watch, one or more { capabilityId, params }, for example tiktok:hashtag-videos with { "hashtag": "yourbrand" }. One monitor can watch several platforms, and their new items arrive together. tiktok:hashtag-videos also takes pages (1–7, how far down the hashtag each check reads, 30 posts a page; TikTok lists its top 170 to 200 or so, popular first, so 7 reads them all) and requireHashtag (true: only posts whose own caption carries the tag). Changing either keeps the monitor's history.
  • schedule.intervalMinutes: one of 5, 15, 60, 360, 1440. Optional quietHoursStart/quietHoursEnd (0–23) and timezone.
  • delivery: where new items go: webhook (your https URL gets JSON), email, slack or discord. Defaults to your account email.
  • filters: includeKeywords, excludeKeywords, and an optional AI relevance filter (aiEnabled with aiCriteria in plain English).
  • maxAlertsPerDay: a safety cap, up to 10,000 for a monitor made with a key. name is optional.
bash
curl -X POST https://api.fetchlayer.dev/monitors \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "#yourbrand on TikTok",
    "sources": [{ "capabilityId": "tiktok:hashtag-videos", "params": { "hashtag": "yourbrand" } }],
    "schedule": { "intervalMinutes": 60 },
    "delivery": [{ "type": "webhook", "target": "https://example.com/hooks/fetchlayer" }],
    "maxAlertsPerDay": 5000
  }'

The answer is 201 with the monitor. Its first check takes a silent first look: everything already there is recorded as seen, so you are only told about what appears after it. A monitor made with a key runs its first check within its first interval (at most an hour), at a time spread across that interval, so that many monitors created together don't all run at the same moment. nextRunAt says when.

Each item once, for good

An item a monitor has seen is never sent again, however long it stays listed and whatever you change about how the monitor checks. Pointing a platform at a different subject (another hashtag) starts that platform over with a new first look.

List, read, update, delete

  • GET /monitors: every monitor on the account, newest first.
  • GET /monitors/:id: one monitor, its latest results and its recent checks.
  • PATCH /monitors/:id: send the full monitor (the same fields as create) to change it. Delivery targets come back masked, because a webhook URL is a credential. Send { "type": "webhook", "keep": true } to keep the stored one.
  • PATCH /monitors/:id with only { "paused": true } or { "paused": false }: pause or resume. Resuming runs a check straight away.
  • DELETE /monitors/:id: removes the monitor, its results and its delivery log.

Read results with a cursor

GET /monitors/:id/hits pages through what the monitor kept. For a daily job, ask oldest first from your last pull, and follow nextCursor until it is null:

  • order: asc (oldest first) or desc (newest first, the default).
  • since: ISO 8601; only results recorded at or after it.
  • limit: 1–100, default 25.
  • cursor: the previous page's nextCursor, unchanged, with the same order. Paging is exact: nothing is skipped or repeated, even while new results arrive.
  • view=filtered: what the filters left out, instead of what was kept. platform: one platform's results.
bash
curl "https://api.fetchlayer.dev/monitors/<id>/hits?order=asc&since=2026-11-10T00:00:00Z&limit=100" \
  -H "Authorization: Bearer ss-your-key"
json
{
  "hits": [
    {
      "id": "…",
      "capabilityId": "tiktok:hashtag-videos",
      "verdict": "matched",
      "delivery": "sent",
      "createdAt": "2026-11-10T14:02:11.204Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJ0Ijoi…"
}

What a webhook receives

One JSON POST per check that found something, with every new item from every platform the monitor watches. Each item has a stable id, its platform, the summary fields, and in raw the platform's full record for it: for a TikTok video, the same video object the TikTok endpoints return.

json
{
  "event": "monitor.items",
  "deliveryId": "2f0c…",
  "monitor": {
    "id": "…",
    "name": "#yourbrand on TikTok",
    "url": "https://fetchlayer.dev/dashboard/monitors/…"
  },
  "capability": "tiktok:hashtag-videos",
  "count": 1,
  "digest": "new",
  "deferredCount": 0,
  "contentAvailable": true,
  "items": [
    {
      "id": "673a…",
      "capabilityId": "tiktok:hashtag-videos",
      "body": "caption…",
      "author": "someone",
      "url": "https://www.tiktok.com/@someone/video/…",
      "score": 1520,
      "publishedAt": "2026-11-10T13:58:00.000Z",
      "matchReason": null,
      "raw": {
        "id": "…",
        "description": "caption…",
        "stats": {
          "playCount": 1520
        }
      }
    }
  ]
}

Headers on every POST:

  • X-FetchLayer-Delivery: the same on every attempt of one POST (also deliveryId in the body). If you already handled it, answer 2xx and drop it. Each item's id is stable too, so a repeated item is safe to ignore.
  • X-FetchLayer-Attempt: 1 to 5. X-FetchLayer-Event: monitor.items.
  • X-FetchLayer-Signature: t=<unix seconds>,v1=<hex>, an HMAC-SHA256 of <t>.<raw body> keyed with the monitor's webhook secret.
javascript
import crypto from 'node:crypto';

function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // too old: a replay
  const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));
}

The secret (whsec_…) is returned once, as webhookSecret, when you create a monitor with a webhook or add one to it. Send PATCH /monitors/:id with { "rotateWebhookSecret": true } to get a new one; the old one stops verifying at once.

Retries

Answer with any 2xx within 10 seconds. Anything else is tried again after 1, 5, 15 and 40 minutes: 5 attempts over about an hour, with the same delivery id and the same items. A check that fails is retried inside its own interval too, so one bad minute does not cost you an hour.

GET /monitors/:id/deliveries is the delivery log, kept for 30 days. Each row is one POST: its id, how many items it carried, its state (delivered, retrying, failed), and every attempt's status and time. Filter with ?status=, ?limit= and ?before=. The same log is on the monitor's page in the dashboard.

digest: "backlog" marks the one message a new monitor may send about what was already there when it started.

Where results are readable

A monitor's deliveries is either server-readable or sealed. With server-readable, each result's item and raw record are kept, encrypted, for 7 days. That lets a retried webhook carry the items, and lets GET /monitors/:id/hits return them (the summary fields plus raw). With sealed, results can be read only on your own signed-in devices. An alert sent after the moment of finding then gives the count (deferredCount, contentAvailable: false) instead of the items. A new monitor is sealed unless you say otherwise or your account has another default; every monitor's deliveries field says which it is. A server-readable copy is deleted 7 days after the result was found, whether or not it was delivered. Set it when you create the monitor, or change it on its own with PATCH /monitors/:id and { "deliveries": "sealed" }. Switching back to sealed deletes the readable copies at once.

Errors and billing

401: a missing or invalid key. 403: a key scoped to other platforms, a trial key, an account at its monitor limit, or a route that is only in the dashboard. 404: a monitor that is not yours. 400: names the field that is wrong. 429: slow down. Each check is billed like the same API call made with your key, for every platform it reads; a check that cannot reach a platform costs nothing.

json
{
  "error": "Pick one of the offered check frequencies."
}