Listening
Standing keyword queries scoped to brand, competitor, or topic that poll networks for matches, roll them up into volume, sentiment, and share-of-voice views, and fire alerts on spikes and sentiment drops.
Listening
Social listening watches the wider conversation, not just replies to your own
posts. You define standing keyword queries, Pact polls the configured
networks for matches, and the matches roll up into a dashboard of volume over
time, sentiment trend, and share of voice — with alerts that fire when a
rule trips. The surface is served under /v1/social/listening
(api/routes/social_listening.py) and backed by the tenant_listening_queries,
social_listening_matches, and social_listening_alerts tables.
Live surface
Query CRUD, polling, match listing, the rollup dashboard, and alert CRUD/evaluation are all real, tenant-scoped endpoints.
Queries
A query (GET/POST /v1/social/listening/queries) has a label, a keyword
(up to 512 chars), a scope, and an optional list of providers to watch:
brand— your own names and handles.competitor— rival brands, for share-of-voice comparison.topic— a theme or hashtag you want to track.
Leaving providers empty watches every connected network the query can reach.
Queries can be enabled/disabled, updated (PATCH), and soft-deleted (DELETE).
Polling and matches
POST /v1/social/listening/poll runs one polling pass and returns a summary of
what it found; each new hit becomes a row in social_listening_matches with a
sentiment label and score. GET /v1/social/listening/matches lists them,
filterable by query and by a since timestamp. Every query tracks its
last_polled_at so you can see freshness at a glance.
The rollup dashboard
GET /v1/social/listening/dashboard returns three rollups the UI charts:
volume_by_day— match count per day.sentiment_trend— average sentiment and count per day.share_of_voice— match counts grouped by label and scope, so you can put brand mentions next to competitor mentions.
Alerts
Alerts (GET/POST /v1/social/listening/alerts) attach a rule to your
listening stream. Three rule kinds ship today:
volume_spike— mention volume jumps past a threshold.sentiment_drop— average sentiment falls.competitor_launch— a competitor-scoped query lights up.
POST /v1/social/listening/alerts/evaluate runs an evaluation pass and returns
the list of alerts that fired; the engine emits a
social.listening.alert.fired audit event per trigger, alongside
social.listening.poll.completed and the query/alert lifecycle events.
Coverage tracks your ingestion
Listening only sees the networks you've connected and configured to poll. A query scoped to a provider without valid app credentials returns no matches — completeness depends on what you've wired up in Social settings.