Skip to main content
POST
Create an engagement watch

Authorizations

Authorization
string
header
required

Account API key passed in the Authorization header

Query Parameters

account_id
string

Target account UUID. Required for staff callers; ignored for customer API keys.

Body

application/json
kind
enum<string>
required

topic or company.

Available options:
topic,
company
name
string
required

Your label for this watch.

Minimum string length: 1
company_linkedin_id
string

Required for kind=company, and rejected for kind=topic. The competitor's numeric LinkedIn ID.

countries
string[] | null

ISO 3166-1 alpha-2 codes to keep. Omit for no country restriction. This filters engagers; it is never written onto them.

is_enabled
boolean

Defaults to true.

keywords
string

Required for kind=topic, and rejected for kind=company. A LinkedIn boolean query, passed through as written: "lean manufacturing" OR "visual management".

max_engagers_per_post
integer<int32>

How many engagers are read per post. Defaults to 25. Spend per sweep is this times max_posts_per_sweep.

Required range: 1 <= x <= 500
max_posts_per_sweep
integer<int32>

How many posts one sweep looks at. Defaults to 10.

Required range: 1 <= x <= 100
persona_ids
string[] | null

Personas deciding which engagers count as leads, from GET /v2/personas. Omit to keep everyone who engaged. Engagers matching none are still recorded, so widening a persona later surfaces people already collected.

Response

OK

countries
string[] | null
required

ISO 3166-1 alpha-2 codes to keep. Empty means no country restriction.

created_at
string<date-time>
required
id
string
required
is_enabled
boolean
required

A disabled watch is not swept and costs nothing, but keeps its history.

kind
string
required

topic or company.

Example:

"topic"

max_engagers_per_post
integer<int32>
required

Cost dial: how many engagers are read per post. Spend per sweep is this times max_posts_per_sweep.

max_posts_per_sweep
integer<int32>
required

Cost dial: how many posts one sweep will look at.

name
string
required

Your label for this watch.

Example:

"Lean manufacturing"

persona_ids
string[] | null
required

Personas that decide which engagers count as leads. Empty keeps everyone who engaged.

updated_at
string<date-time>
required
company_linkedin_id
string

Company watches only: the competitor's numeric LinkedIn ID.

keywords
string

Topic watches only: the boolean query, exactly as you wrote it.

last_sweep_engagers_collected
integer<int32>

How many people the last run collected. Zero after a completed sweep means nobody engaged, which is different from the watch not having run.

last_sweep_outcome
string

What the last run did. One of:

  • completed: it ran, and last_sweep_engagers_collected says what it found. Zero is a real answer.
  • out_of_credits: skipped before spending, because the account could not pay for a single person. This is the one to check when a feed goes quiet — topping up resumes it on the next sweep.
  • failed: it ran and something went wrong, usually the provider. Self-correcting, since the next sweep re-reads an overlapping window.
last_swept_at
string<date-time>

When this watch last ran. Absent until its first sweep.