Skip to main content
POST
people.changes.monitor.create

Authorizations

Authorization
string
header
required

API key: sk_live_…

Headers

Idempotency-Key
string
required

Required: this capability has an external effect.

Maximum string length: 255
Pramaan-Max-Price-Micro
string

Optional. The most this request may be priced at, in micro-USD (a whole number above 0). It replaces the capability's own price ceiling for this request, lower or higher. Sources that could cost more are left out; when none is left the answer is 400 with the lowest limit that would work.

Pattern: ^[1-9]\d{0,14}$

Body

application/json
profileUrls
string[]
required

The public profile URLs of the people to watch, up to 10,000.

Required array length: 1 - 10000 elements
track
object
required

The change that fires a delivery: a leaf, or an and/or group of leaves. An and group fires when every condition holds and at least one just became true.

everyHours
integer
default:24

How often the monitor checks and notifies, in hours. Default 24. Checking more often does not raise the price: you pay per changed person.

Required range: 1 <= x <= 744
maxResultsPerRun
number

Changed people delivered per run, 1 to 10,000. Default 25. Above 1,000 the run is delivered as one file that data.monitor.run.read fetches for you.

Required range: x >= 1
refreshFrequencyDays
default:30

How many days fresh the tracked data is kept: 30 (default, 5 credits per changed person), 14 (10), 7 (20), 3 (50) or 1 (150 credits, the dearest option, never the default). Freshness, not the checking cadence, decides how soon a change is seen.

expiresAt
string

Stop the monitor after this date, YYYY-MM-DD.

preferredHour
integer

Hour of day in UTC the runs prefer.

Required range: 0 <= x <= 23
label
string

A label for the monitor.

Required string length: 1 - 100

Response

The result

kind
enum<string>
required

A saved search (discovery) or a watched list (entity).

Available options:
discovery,
entity
dataset
enum<string>
required

What kind of record the monitor delivers.

Available options:
company,
person,
job,
social_post
everyHours
number
required

The schedule: the monitor runs every N hours.

maxResultsPerRun
number
required

Records delivered per run, at most.

status
enum<string>

Current state of the monitor.

Available options:
active,
paused,
suspended,
expired,
cancelled
realtime
boolean

True when every run searches live (the 1-day tier) instead of the index.

refreshDays
number

How many days fresh the tracked data is kept (watched-list monitors).

label
string

The monitor's label.

createdAt
string

When the monitor was created, ISO 8601.

lastRunAt
string

When the monitor last ran, ISO 8601.

ref
string

Reference to what this call created. Pass it as ref to data.monitor.update.