Skip to main content
POST
people.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
domain
string

Company domain the people work at, e.g. figma.com.

Required string length: 1 - 256
title
string

Job title the people hold now, e.g. Head of Revenue Operations.

Required string length: 1 - 256
fullName
string

A person's full name.

Required string length: 1 - 256
country
string

Two-letter country code like GB.

Required string length: 1 - 2
Pattern: ^[A-Z]{2}$
location
string

Free-text place, e.g. "London, United Kingdom".

Required string length: 1 - 256
keywords
string[]

Skills or topics the people should match.

Maximum array length: 10
Required string length: 1 - 128
everyHours
integer
default:24

How often the monitor runs, in hours. Default 24. A realtime monitor runs at most daily.

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

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
isRealtime
boolean
default:false

Search live on every run instead of the index: finds people the index has not seen yet, at the dearest per-record price (150 credits against 0.5). The dearest option, never the default; runs at most once a day, and only title, employer domain and country can be asked live (fullName, location and keywords are refused here).

narrowBy
object

Realtime only: index filters applied to each person the live search returns, so they can only drop results. Requires isRealtime.

overflow
enum<string>
default:redeliver

What happens to matches beyond maxResultsPerRun: redeliver holds them for a later run (default), drop discards them.

Available options:
redeliver,
drop
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.