Monitors

Watch LinkedIn, X, Instagram and TikTok accounts and topics on a schedule, and get new relevant activity by webhook or API.

POST /v1/monitors

A monitor turns a plain-language query, such as "New LinkedIn posts from Nvidia about AI chips", into a plan of accounts and topics to watch. On each scheduled run Ploid fetches new activity from those targets, keeps only the items that match the query, and delivers them to your webhook and to the items endpoint. Creating a monitor takes a few seconds while the query is compiled.

Requires an API key with the people:search scope. You can also try it in the API playground. The full request and response schemas are in the OpenAPI document under the Monitors tag.

Create a monitor

curl https://api.ploid.com/v1/monitors \
  -H "Authorization: Bearer $PLOID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nvidia news",
    "query": "New LinkedIn posts from Nvidia about AI chips",
    "schedule": { "preset": "daily" },
    "webhook_url": "https://example.com/ploid-webhook"
  }'

Field	Meaning
`query`	Required. What to watch for, in plain language, up to 1,000 characters. Name the accounts, companies, keywords or hashtags to watch.
`schedule`	Required. `{ "preset": "hourly" \| "daily" \| "weekly" }` or `{ "cron": "0 9 * * 1" }`, each with an optional IANA `timezone`. Runs are at most hourly.
`name`	Optional, up to 120 characters. Derived from the query when omitted.
`output`	Optional. `{ "type": "text" }` (default) returns a `summary` per item. `{ "type": "object" }` returns fields from your `schema` or `description`.
`plan`	Optional. Explicit `targets` (`platform`, `kind`, `identifier`, `events`) and `relevance_criteria`, used instead of compiling the query.
`webhook_url`	Optional HTTPS URL that receives run events.
`webhook_secret`	Optional, 16 to 256 characters. Signs deliveries: `X-Ploid-Signature: sha256=<hex HMAC-SHA256 of the raw body>`.
`max_items_per_run`	Optional, 1 to 100 (default 25). The most items one run emits.

The response is 201 with the monitor. meta.baseline_run_id is the silent first run that records what already exists, so later runs only emit new activity. meta.unresolved lists mentions in the query that could not be turned into a target. A query that resolves to no target returns 422 no_targets. Preview the plan without creating anything with POST /v1/monitors/compile.

Targets cover linkedin, x, instagram and tiktok. kind is profile, company (LinkedIn only), keyword or hashtag; events are posts (default), engagement, profile and company. Topics support posts only, and Instagram supports hashtags but not keyword search.

Update, pause or resume

curl -X PATCH https://api.ploid.com/v1/monitors/$MONITOR_ID \
  -H "Authorization: Bearer $PLOID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

PATCH /v1/monitors/{id} accepts any of name, status (active or paused), query, schedule, output, plan, webhook_url, webhook_secret and max_items_per_run. Send null for webhook_url or webhook_secret to remove them. Changing query or plan replaces the targets and starts a new baseline run, returned as meta.baseline_run_id. It is null when a run is already in progress; the next run then sets the baseline.

Endpoints

Endpoint	What it does
`POST /v1/monitors/compile`	Preview the plan and output schema for a query. Creates nothing.
`POST /v1/monitors`	Create a monitor and start its baseline run.
`GET /v1/monitors`	List monitors, newest first.
`GET /v1/monitors/{id}`	Get one monitor.
`PATCH /v1/monitors/{id}`	Update, pause or resume a monitor.
`DELETE /v1/monitors/{id}`	Delete (disable) a monitor. Deleted monitors cannot be updated or run.
`POST /v1/monitors/{id}/run`	Queue a run now. `409` while a run is already in progress.
`POST /v1/monitors/{id}/test`	Dry run: what the monitor would find right now. Saves nothing and sends no webhook.
`POST /v1/monitors/{id}/webhook/test`	Send a `monitor.webhook.test` event to `webhook_url` once and return the HTTP outcome. No ACU.
`GET /v1/monitors/{id}/runs`	List runs, newest first. Each run has `status`, `candidates`, `items_emitted`, `acu_charged` and `webhook`.
`GET /v1/monitors/{id}/runs/{runId}`	Get one run.
`GET /v1/monitors/{id}/items`	List emitted items, newest first. Filter by `run_id`.

List endpoints take limit (up to 100) and cursor, the next_cursor from the previous page.

The webhook test event is signed with X-Ploid-Signature only when the monitor has a webhook_secret; the response's signed field says which.

Items and webhooks

Each item has platform, event (post.created, engagement.created, profile.changed, company.changed or job.posted), the target it came from, url, occurred_at, a relevance score and reason, output in the monitor's output shape, and the normalized source activity.

Runs send monitor.run.completed when they emit items (with up to 100 of them), monitor.run.failed, and monitor.run.skipped. A run is skipped when available ACU or the API-key budget cannot cover it. After 5 consecutive failed runs the monitor is paused.

Pricing and limits

Compiling and creating a monitor cost 1 ACU each, and so does a PATCH that changes query, plan or output. A test (POST /v1/monitors/{id}/test) costs 1 ACU per target fetched. Each run costs 1 ACU per target fetched plus 1 ACU per emitted item; baseline runs emit nothing. A workspace can have at most 50 monitors, active or paused (409 monitor_limit_reached); deleting one frees a slot. A monitor has at most 10 targets. See Errors & rate limits.