Monitors are enabled per organization. Contact support to turn them on.
API Reference
See the full request/response schema and parameters in the API Reference.
LinkedIn field discovery is documented in LinkedIn Monitors. Every other endpoint here applies to both monitor types.
Create monitor
Create one monitor from a table, with one row per company or person.Request
Parameters
Creation is all or nothing. If any row is invalid, nothing is created. See Billing for what creation checks.
Response
The response is201 with the monitor, without its rows. Read them with List rows.
Metadata
metadata is stored on the monitor and its rows. It is echoed in the payload of change and established events and in every notification. Updating metadata replaces the whole object.
Create monitor from a file
Create one monitor from a file, with one row per company or person. Use this endpoint for large tables: the request returns as soon as the file is checked, and the rows are added afterwards. The request ismultipart/form-data with two parts.
Every column in
key_columns must exist in the file. The Idempotency-Key header works as it does on Create monitor.
202 with the monitor, without its rows. status is starting and row_count is 0. Rows are added in the file’s order, and row_count rises as they arrive. When every row is in, status becomes active and next_run_times is populated. Poll Get monitor to follow progress.
While status is starting, no row is checked or billed, and the monitor cannot start a run. A cancel request is accepted: the rows finish adding and the monitor stays canceled.
If adding rows fails, status becomes failed and disabled_reason explains the failure. Send the same request again to finish it: rows that were already added are kept, and only the missing rows are written.
Uploads are rate limited; see Rate Limits.
List monitors
List your team’s monitors, newest first. Rows are not included.cURL
The response is
{ "items": [...], "next_cursor": "..." }. A page can hold fewer than page_size monitors before the last page. Keep requesting pages until next_cursor is null.
Get monitor
Retrieve a monitor: its settings,status, and row counts. The response has the same fields as Create monitor.
cURL
Paused and canceled monitors return
next_run_times: [].
Disabled reasons
disabled_reason says why a monitor or one of its rows is not checked. It is null while checks run.
Update monitor
Change a monitor’s settings, or pause and resume it. Fields you omit keep their current value.name, frequency, tier, webhook_url, webhook_event_types, metadata, is_active, and criteria (LinkedIn monitors only). Changes apply to every row. The response is the updated monitor.
fieldsis fixed at creation. To watch different fields, create a new monitor.is_active: falsepauses the whole monitor and setsdisabled_reason: "paused".is_active: trueresumes it. A row you switched off stays off when the monitor resumes.webhook_event_typesandmetadatareplace the stored value.- Changing
tierchecks tier access and the team’s credit limit.
Start a run
Check every active row now, without waiting for the schedule.cURL
202. Only a monitor whose status is active can start a run. If a run is already going, no new run starts and the response is the same. Follow the run with List monitor runs.
A run you start is billed like a scheduled check. See Credit Costs.
Cancel monitor
Permanently stop future checks for the whole monitor. Values and history stay readable. Cancellation cannot be undone. To stop checks for a while, pause the monitor instead.cURL
status: "canceled", is_active: false, disabled_reason: "canceled", and next_run_times: []. Canceling again returns the canceled monitor.
List rows
List a monitor’s rows, switched-off rows included, in the order they were added.cURL
subject holds the row’s key column values. values holds the current value of each watched field. To read the whole table at once as CSV, download a snapshot instead.
Get row
Retrieve one row, including the current value of each watched field. The response is one row object from List rows.cURL
Switch a row on or off
Include or exclude one row from checks. The response is the updated row.cURL
is_active is required. Send true to include the row again. A switched-off row is skipped on every check, is not billed, and keeps its values and history. Its disabled_reason is excluded. Rows of a canceled monitor cannot be changed.
List row events
List what changed on one row over time, newest first.cURL
next_cursor is always null: a request returns at most the newest 500 events that match its filters. Narrow it with field or event_group_id, or read older values from snapshots. See Events for every event type.
List monitor runs
List a monitor’s runs, newest first. A run is one scheduled or started check of the whole monitor.cURL
status is running, succeeded, or failed. Counts are final once the run is no longer running. rows_checked includes checks that found no change. A succeeded run can include failed row checks, reported in rows_failed.
A run is failed when it stops before every row finishes. A failed run sends no monitor.run.completed notification, and its changed rows are not available from Get a run’s changed rows. The other rows’ changes are still recorded: read them from row events or snapshots.
Both run endpoints accept page_size (default 100, maximum 500) and cursor.
Get a run’s changed rows
Retrieve only the rows a succeeded run changed, with the previous and current value of each changed field. Starting values and unchanged rows are excluded.cURL
running returns 409; wait until its status is succeeded.
List latest changes
Retrieve, for every row, when each watched field last changed. Use it to highlight recently changed cells without reading every row’s events.cURL
change event. Rows and fields that never changed are omitted, so a monitor with no changes returns {}.
List snapshots
List every moment the monitor’s data changed, newest first, each with a download URL. A snapshot is recorded for each second in which a value was established or changed.cURL
Download snapshot
Download the table as it stood at a moment, as CSV: one row per subject, with the key columns followed by the watched fields.cURL
as_of is latest for the current values, or an as_of value from List snapshots, URL-encoded. The snapshot’s url is already encoded; request it with your API key. Add page_size (1 to 1000) to return only the first rows as a preview.
Cells hold the stored values unchanged, including any a spreadsheet would run as a formula.
Export history
Download many snapshots at once as a ZIP of CSVs, one file per snapshot. Each file has the same columns as Download snapshot.
An export is limited to 5,000 snapshots and 50 MiB of CSV. A larger export, or a range with no snapshots, is refused before any data is sent; select fewer snapshots or a shorter range.
Exports are rate limited; see Rate Limits. On
429 or 503, wait for Retry-After and send the request again, as the examples do.
Create a LinkedIn monitor from multiple profiles
Sendtype: "linkedin", subject_type: "person", and key_columns: ["linkedin_url"]. Each row holds only a LinkedIn profile URL. fields is a list of keys from GET /v1/monitors/linkedin-fields. The table has one monitor ID and one schedule.