Signals

Create Listener

Start watching something.

THIS CAN SPEND CREDITS: a brand listener with no query has one built by an LLM call, which is charged. Supply query, or call POST /social-listeners/queries/generate first, to see what you are committing to.

A user listener additionally resolves target_handle against the platform, which consumes the org's X API quota.

Set monthly_credit_cap unless you have set an org-wide one - it is the only per-listener bound on what this costs.

post/social-listeners

Request

Base URL: https://be.graph8.com/api/v1
URL: https://be.graph8.com/api/v1/social-listeners
Auth: HTTP bearer

Headers

Authorizationstring nullable

X-Target-Org-Idstring nullable

Request body

platform'x' | 'linkedin' | 'reddit' | 'instagram' | 'youtube'

listener_type'brand' | 'competitor' | 'keyword' | 'engagement' | 'user' required

brand and competitor watch a named entity, keyword watches a query, engagement watches an ICP-shaped bucket, user watches one account's posts.

namestring required

querystring nullable

Platform-native search query. OMITTING this on a brand listener makes the app build one with an LLM call, which SPENDS CREDITS. Supply a query, or call POST /social-listeners/queries/generate first if you want to see it before committing.

target_handlestring nullable

Required for a user listener: the account to watch.

filtersobject

poll_interval_secinteger nullable

How often the worker polls. Shorter means more matches AND more spend.

monthly_credit_capinteger nullable

Per-listener ceiling on credits. The one field that BOUNDS what this costs.

force_rebuild_brandboolean

Rebuild a brand query even though one exists. Spends a credit to do it.

Response

Successful Response

dataSocialPayload required

One social-listening object, or one handler response.

Open-shaped: these payloads carry per-platform detail that differs between X, LinkedIn, Reddit, Instagram and YouTube and grows with them.

Changes

No recorded changes to this operation across all 2 revisions of this API.