Skip to main content
POST
Create a monitor

Authorizations

​
pubrio-api-key
string
header
required

A unique API token that represents the actions you perform through the API and the corresponding permissions and operations. You can create it through the Settings section.

Body

application/json
​
query
string
required

A natural-language description of the monitor (any language), e.g. "monitor companies expanding into Japan, get C-level people with their work email, and email alerts to [email protected] in real time". It is interpreted into the fields below (detection_mode, signal_types, signal_filters, people_enrichment_configs, destination_type/destination_config, frequency_minute) in the same request. Any field you also pass explicitly overrides the interpreted value. If the text is not a monitor request, the call returns 400. Capped at 2000 characters.

Maximum string length: 2000
​
name
string

Name of the monitor.

​
description
string

Description of the monitor.

​
status
enum<string>
default:active

Lifecycle status to create the monitor with. Defaults to active. Use draft to save a half-built monitor: only name is required, validation is deferred until you activate it, and a draft never runs.

Available options:
draft,
active,
paused,
inactive
​
detection_mode
enum<string>

How signals are detected. signal_first scans the market broadly; company_first tracks a named account list and requires at least one company, domain or LinkedIn URL. Immutable after creation — changing it on an existing monitor returns 40021. Create a new monitor instead.

Available options:
company_first,
signal_first
​
signal_types
enum<string>[]

Types of signals to monitor.

Available options:
jobs,
news,
advertisements,
expansions,
cloud_footprints
​
signal_filters
object[]

One entry per signal stream the monitor watches.

Example:
​
company_filters
object

Global company filters applied as a second layer across all signal types. Accepts the same parameters as the Company Search endpoint — locations, employees, technologies, verticals, and more.

Example:
​
companies
string<uuid>[]

List of company domain_search_id UUIDs to monitor. Used primarily in company_first mode to specify target companies. You can also use domains or linkedin_urls as alternatives — only one of the three is required.

​
domains
string[]

List of company domains to monitor (e.g., ["openai.com", "google.com"]). Alternative to companies — Pubrio resolves these to the corresponding companies. Only one of companies, domains, or linkedin_urls is required.

​
linkedin_urls
string<uri>[]

List of LinkedIn company URLs to monitor (e.g., ["https://linkedin.com/company/pubrio"]). Alternative to companies — Pubrio resolves these to the corresponding companies. Only one of companies, domains, or linkedin_urls is required.

​
is_company_enrichment
boolean

Whether to enrich company data in results.

​
is_people_enrichment
boolean

Whether to enrich people data in results.

​
people_enrichment_configs
object[]

Array of people enrichment layers. Each layer runs an independent people search. Contains max_people_to_return (1-25), people_contact_types (array — refers to Redeem contact types: email-work, email-personal, phone), and filters (same parameters as People Search endpoint).

Example:
​
destination_type
enum<string>

Delivery destination type.

Available options:
webhook,
email,
sequences
​
destination_config
object

Configuration for the destination. For webhook: requires webhook_url (string), optional headers (object) and body (object). For email: accepts email (string) or emails (array of strings). For sequences: requires sequence_identifier (string) plus at least one of is_people_search_enrolled / is_company_contact_enrolled set to true.

Example:
​
frequency_minute
integer
default:0

Trigger frequency in minutes. Min: 0, Max: 10080, Default: 0.

Required range: 0 <= x <= 10080
​
max_failure_trigger
integer
default:5

Maximum consecutive failures before pausing the monitor. Min: 1, Max: 10, Default: 5.

Required range: 1 <= x <= 10
​
max_daily_trigger
integer
default:500

Maximum triggers per day. Min: 0, Max: 86400, Default: 500.

Required range: 0 <= x <= 86400
​
max_records_per_trigger
integer
default:25

Controls the maximum number of records delivered per trigger. Lower values reduce payload size per delivery, which is recommended for large result sets or rate-limited integrations. Min: 1, Max: 100, Default: 25. See Setting up Webhooks for guidance.

Required range: 1 <= x <= 100
​
excluded_companies
string[]

Companies this monitor never delivers or bills, as domain_search_id UUIDs. Applied in both detection modes at run time, before enrichment and billing; a company on both companies and this list is excluded while it stays on the list. Max list size: 100,000 (resolved ids across excluded_companies, excluded_domains and excluded_linkedin_urls).

Example:
​
excluded_domains
string[]

Company domains to exclude (e.g. ["existing-client.com"]). Resolved to companies and merged into excluded_companies.

Example:
​
excluded_linkedin_urls
string[]

LinkedIn company URLs to exclude. Resolved to companies and merged into excluded_companies.

Example:
​
record_unit
enum<string>

What one delivered record is: signal (payload signals[], one entry per signal) or company (payload companies[], one entry per company with its signals nested). Default follows detection_mode: signal_first → signal, company_first → company. Caps (max_records_per_trigger, max_daily_records) count this unit.

Available options:
signal,
company
Example:

"company"

​
company_dedupe_days
integer

A company appears in at most one delivery per this many days, across all the monitor's signal types; a company delivered inside the window is left out of later deliveries and its later signals in the window are skipped, not queued. 0 = off. Default: 0.

Required range: x >= 0
Example:

30

​
is_newest_first
boolean

Deliver the freshest matching signals first. With a per-trigger or daily cap the newest records are kept and the monitor's cursor still moves to the newest fetched row, so older rows are skipped, never queued. Default false (oldest first, nothing skipped).

Example:

true

​
max_daily_records
integer

Hard cap on records delivered per calendar day in the owner's timezone (0 = unlimited). Counted in the monitor's record unit over successful deliveries; a trigger delivers at most the remaining budget, then the monitor waits for the next day without moving its cursor. Default: 0.

Required range: x >= 0
Example:

200

​
notification_email
string<email>

Email address for monitor failure notifications.

​
max_retry_per_trigger
integer
default:1

Maximum retries per trigger. Min: 0, Max: 3, Default: 1.

Required range: 0 <= x <= 3
​
retry_delay_second
integer
default:1

Delay between retries in seconds. Min: 1, Max: 5, Default: 1.

Required range: 1 <= x <= 5
​
deep
boolean

Optional, only used with query. Run the reflection pass for higher interpretation accuracy (default true; roughly doubles the interpretation latency). Set false for a faster single pass.

Response

Successful response containing the newly created monitor details.

​
metadata
object
​
data
object
Last modified on August 28, 2026