monitors

Create a monitor

Creates a monitor: a saved recipe plus the parameters to replay, a cadence, and a webhook to deliver each result to. The recipe is any GET endpoint or Prism composite in the catalogue, given as its path without the /v1/ prefix. The batch endpoints that read a JSON body (prism/post-stats, prism/comment-lookup, prism/profiles, youtube/transcripts, youtube/videos, youtube/channels) are POST and cannot be monitored; call them directly. The first run is at next_run_at, the next slot of the cadence. The signing secret is returned exactly once, in this response.

Add track to make a numbers-only monitor: every run reads the paths you list off the unified response (the same shape a /v1 call returns), stores those numbers per row plus the change against the previous run, and keeps nothing else. webhook_url then becomes optional (read the numbers with GET /v1/monitors/{id}/export or /timeseries), and webhook_format: "rows" delivers flat rows ready to append to a spreadsheet. Without track a monitor behaves exactly as before.

post/monitors

Request

  • Base URL: https://www.socialcrawl.dev/v1
  • URL: https://www.socialcrawl.dev/v1/monitors
  • Auth: API key in header x-api-key

Request body

cadencestring required

How often to re-run the recipe: "hourly", "daily", "weekly", or { "cron": "0 9 * * 1" }. One hour is the shortest interval available: a cron that fires more often is accepted, flagged, and then throttled up to the one-hour floor, so a 30-minute schedule runs hourly.

namestring

Label for the monitor. Defaults to "<recipe> monitor".

output_schemaobject

Optional projection applied to each stored run result.

paramsobject

The recipe's own parameters, frozen at create time and replayed verbatim on every run. Required parameters are validated here, not at the first run.

recipestring required

Endpoint path without the /v1/ prefix, for example search/everywhere or prism/comments. Must be a GET endpoint.

suppress_webhook_unless_alertboolean

When true, only a run with at least one fired alert delivers a webhook. The run still executes and is still billed.

webhook_format'full' | 'rows'

full: the run payload. With track it carries result (the unified response, delivered but not stored), numbers and deltas. rows (needs track): { monitor_id, run_id, recipe, status, scheduled_for, alerts_fired, rows: [{ t, row_id, metric, value, prev, abs_change, pct_change }] }, one entry per row and metric. Same signature either way.

webhook_secretstring

Supply your own signing secret, or leave it out and one is generated. Either way it is returned exactly once and stored encrypted.

webhook_urlstring

HTTPS URL on a public host. Loopback, private and link-local addresses are rejected. Required unless track is set; a monitor with track and no webhook_url is download-only.

Example request

{
  "cadence": "daily",
  "params": {
    "url": "https://www.instagram.com/p/DAbc123"
  },
  "recipe": "prism/comments",
  "track": {
    "metrics": [
      "items[].post.engagement.views"
    ]
  }
}

Response

Monitor created. webhook_secret appears in this response and never again.

webhook_secretstring nullable

The HMAC-SHA256 signing secret for this monitor's webhook. Store it now. Null for a download-only monitor.

Example response

{
  "monitor": {
    "recipe": "prism/comments"
  },
  "webhook_secret": "whsec_..."
}

Changes

No recorded changes to this operation across all 1 revision of this API.