Skip to main content
GET
Get one listener

Authorizations

Authorization
string
header
required

A workspace API key, created in workspace settings and sent as Authorization: Bearer op_live_…. Session cookies are not accepted. Scopes: signals:read, accounts:read, listeners:read, listeners:analyse, pipeline:read, pipeline:write, collections:write, export:read.

Path Parameters

id
string
required

The id of the resource.

Response

The listener, plus schedulerState read live from the queue. That can disagree with the stored nextRunAt beside it, and when it does the queue is right.

One listener with its full configuration, plus the live state of its repeat schedule read from the queue rather than from the database.

id
string
required

Stable identifier.

orgId
string
required

The workspace this belongs to (org_…).

createdBy
string
required

Clerk user id of whoever created it.

companyName
string
required

The company the listener searches on behalf of.

mode
enum<string>
required

What it listens for. market watches conversations, rivals watches complaints about named competitors, places reads the reviews of local prospects. Derived from objective at creation.

Available options:
market,
rivals,
places
objective
enum<string>
required

What it is for, as the wizard asked.

Available options:
find_customers,
find_competitors,
find_partnerships,
find_dissatisfaction,
find_local_prospects,
custom
sources
enum<string>[]
required

Which platforms each run searches.

A platform.

Available options:
x,
linkedin,
facebook,
reddit,
hackernews,
linkedin_jobs,
indeed,
ashby,
greenhouse,
lever,
google_reviews,
g2,
trustpilot,
youtube,
vendor_community
schedule
string
required

Cron expression. When runs happen.

lookbackHours
integer
required

How far back each run looks for conversations.

Required range: x >= 1
status
enum<string>
required

draft and analysing precede the first run; error means the last run failed.

Available options:
draft,
analysing,
active,
paused,
error
generatedKeywords
string[]
required

The keyword list the crawl produced.

A keyword.

createdAt
string<date-time>
required

When it was created. The pagination sort key.

schedulerState
object
required

What the queue says, which can disagree with nextRunAt above: that field is a stored copy and this is the live answer.

customObjective
string

Free text, when objective is custom.

website
string<uri>

The site the plan was generated from.

description
string

What the business does, as the owner described it.

minRelevanceScore
integer

Classified candidates below this are rejected rather than stored.

Required range: 0 <= x <= 100
sensitivity
enum<string>

The friendly way to pick a bar. minRelevanceScore wins when both are set, so a workspace that tuned the number by hand keeps it.

Available options:
strict,
balanced,
broad
maxRating
integer

Reviews above this many stars never reach the classifier.

Required range: 1 <= x <= 5
blockedDomains
string[]

Domains never worth surfacing: your own site, known competitors.

A hostname.

communityHosts
string[]

The vendor communities a vendor_community listener watches, from the curated registry. Required when that source is selected and meaningless otherwise — the source is pinned to these hosts rather than to one domain of its own.

A community hostname.

notifyEmails
string<email>[]

Who gets run summaries. Falls back to the workspace's list when absent.

An address.

retiredReason
string

Why a listener was paused by something other than its owner, so "why is this off?" has an answer.

billingSuspendedAt
string<date-time>

Set when the listener was paused because the subscription lapsed, rather than because somebody chose to pause it. A separate marker and not a status, so resubscribing restores exactly the set billing stopped.

searchPlan
object

What the listener searches for, generated from the crawl and editable after.

productProfile
object

What this listener's owner sells, for an outreach draft to pitch from. capabilities is a closed list and the draft prompt treats it as one: a model asked to pitch a product it knows only by name invents features, and an invented feature in a first message is a lie told to a stranger in public under the company's name.

rivalProfile
object

Who else the market is paying, and what they say when it disappoints them. painVocabulary is separate from the plan's includeKeywords on purpose: a review reading "rude staff, an hour on hold" shares no keyword with "scheduling software", so the on-topic words for this mode have to be the words of the complaint rather than of the product.

placesProfile
object

Local prospecting: the businesses whose own reviews are read for evidence of the problem this product solves.

autoPipeline
object

What this listener sends to the board by itself. Absent means never configured, which is the same as disabled: a listener that predates this must not start opening deals because a deploy happened.

lastRunAt
string<date-time>

When it last ran. Absent until the first run.

nextRunAt
string<date-time>

When it runs next, as of the last scheduler read.