Social listening API for finding buyers on Reddit and X
updated 13 November 2026
The HearBuyers API is a social listening API that returns buyers instead of raw posts. It reads Reddit and X for the phrases, subreddits, accounts and competitors your project listens for, and scores every public post from 0 to 100 for buying intent. Your code gets the matches: the sentence that matched, the person who wrote it and a drafted reply.
Use it as a social media listening API for your own tools and as a social media monitoring API for your team. You can push buyers into a CRM, build a dashboard, or let an agent work the queue. Every request goes to https://api.hearbuyers.com/v1 with a Bearer key from your project. The same key opens the MCP server, and webhooks push matches to you so you don't have to poll.
Included with Pro and Ultra. Keys are made on your project's API page.
Make your first request
- Start a plan. The API comes with Pro and Ultra, and your first subscription has a 7-day trial.
- Open your project's API page in the app and create a key. Copy it right away. It is shown once.
- Call the API with the key in a Bearer header.
curl "https://api.hearbuyers.com/v1/matches?stage=open&minScore=80&limit=1" \
-H "Authorization: Bearer hb_live_YOUR_KEY"This is the answer. The examples on this page are real responses from a test project with made-up posts. The names and numbers are samples, but the fields and types are exactly what the API returns.
{
"counts": {
"dismissed": 0,
"not_a_fit": 0,
"open": 2,
"replied": 0,
"won": 0
},
"hiddenBelowMinScore": 1,
"items": [
{
"id": "84dab689-a674-4872-ad0f-821dcb1a4866",
"source": "reddit",
"community": "sysadmin",
"authorHandle": "northwind_ops",
"postedAt": "2026-11-13T11:46:01.962518Z",
"score": 92,
"intent": "actively_looking",
"stage": "open",
"keySentence": "We would switch this month if it handles shared inboxes well.",
"hasDraft": true,
"kind": "post",
"listenerIds": [],
"upvotes": 48,
"commentCount": 31,
"likes": null,
"replies": null,
"authorAvatar": "",
"authorVerified": false,
"aboveThreshold": true
}
],
"nextCursor": "1",
"threshold": 70,
"total": 2
}Authentication and keys
Send the key as Authorization: Bearer hb_live_... on every request. A key is hb_live_ followed by 32 letters and digits.
- One key, one project. A key can read and change that project only. It acts as a project admin, so it can move matches between stages and add or remove listeners. It cannot reach billing, the team or any other project.
- Shown once. We store only a hash of the key, so a lost key can't be recovered. Make a new one and revoke the old one.
- Owners and admins make keys. A project can have up to 50 live keys, each with a name of up to 80 characters. The app shows when each key was last used.
- Revoking is immediate. The next request with that key answers 401.
- Call it from a server. The API sends no CORS headers for other sites, and anyone can read a key that sits in browser code.
The API does not post to Reddit or X. Drafts come back as text for a person to review and send.
Rate limits and plans
Each key has its own limit over a rolling minute: 60 requests a minute on Pro, 300 on Ultra. Over the limit, the API answers 429 with a Retry-After header of 60 seconds.
| Plan | Requests per minute | History the API can read |
|---|---|---|
| Pro | 60 | 180 days of matches, leads and overview |
| Ultra | 300 | No limit |
A project needs a live plan: in its trial, active, or past due while Stripe retries the payment. Otherwise every call answers 402 plan_inactive, and the keys work again once the plan does. Adding a listener over your plan's limit answers 402 plan_limit. The pricing page lists the limits.
Filters and paging
GET /v1/matches shows open matches at or above your project's score threshold unless you say otherwise, newest post first.
| Parameter | What it does |
|---|---|
stage | open (default), replied, won, not_a_fit, dismissed, closed (won, not a fit and dismissed together) or all |
source | x or reddit |
minScore | Lowest score to return, 0 to 100. Defaults to the project's threshold, which is 70 until you change it |
since | Only matches found at or after this RFC 3339 time |
limit | 1 to 100, default 50 |
cursor | The nextCursor from the previous page |
The answer holds items, total (every match that fits the filters, not just this page), threshold, hiddenBelowMinScore (matches under your minScore), counts per stage with the same filters, and nextCursor. Keep sending cursor until nextCursor is null. Treat the cursor as opaque.
Leads and brand signals page with limit and offset instead, up to 200 rows a page, 50 by default.
List matches
GET /v1/matches returns one row per match. As a rough guide, 90 and above means the person wants to buy this now, 70 to 89 means a clear need or a comparison of options, and 40 to 69 means a related problem with a weak buying signal.
| Field | Meaning |
|---|---|
id | The match id, used by every other call |
source | x or reddit |
community | The subreddit, or empty for X |
authorHandle | Who wrote the post |
postedAt | When they posted it |
score | Buying intent from 0 to 100 |
intent | actively_looking, comparing, complaining or just_curious |
stage | open, replied, won, not_a_fit or dismissed |
keySentence | The sentence that matched, copied from the post |
hasDraft | Whether a drafted reply, DM or email exists |
kind | post, comment or reply |
listenerIds | The listeners that found it |
upvotes, commentCount | Reddit counts as of the last fetch, null when unknown |
likes, replies | X counts as of the last fetch, null when unknown |
authorAvatar, authorVerified | X profile picture and verified badge |
aboveThreshold | Whether the score reaches the project's threshold |
Get one match
GET /v1/matches/{id} returns the full match: the post, the author, why it matched, the drafts and the history of stage changes.
curl "https://api.hearbuyers.com/v1/matches/MATCH_ID" \
-H "Authorization: Bearer hb_live_YOUR_KEY"{
"aboveThreshold": true,
"author": {
"avatar": "",
"bio": "",
"company": "",
"email": "",
"followers": 0,
"handle": "northwind_ops",
"name": "",
"verified": false,
"website": ""
},
"drafts": [
{
"id": "5fb678f4-15fa-4971-904b-ed8ff69cfd78",
"kind": "reply",
"subject": "",
"body": "Flat pricing and shared inboxes are the two things we built Acme Helpdesk around. Happy to show you how a 9 person team would set it up, no seat fees.",
"status": "draft",
"approvedBy": null,
"approvedAt": null,
"openUrl": "https://www.reddit.com/r/sysadmin/comments/1p3k9aq/looking_for_a_help_desk_tool_that_does_not/"
}
],
"feedback": "",
"foundAt": "2026-11-13T11:46:01.967311Z",
"guidance": {
"level": "",
"note": ""
},
"highlight": {
"end": 271,
"start": 210
},
"history": [],
"id": "84dab689-a674-4872-ad0f-821dcb1a4866",
"intent": "actively_looking",
"keySentence": "We would switch this month if it handles shared inboxes well.",
"listeners": [],
"post": {
"body": "Our support team is growing from 4 to 9 people and Helpwave wants a seat license for each one. Does anyone know a simple help desk with flat pricing? We would switch this month if it handles shared inboxes well.",
"commentCount": 31,
"community": "sysadmin",
"kind": "post",
"likes": null,
"media": [],
"parentTitle": "",
"postedAt": "2026-11-13T11:46:01.962518Z",
"quotes": null,
"replies": null,
"reposts": null,
"source": "reddit",
"text": "Looking for a help desk tool that does not charge per agent\nOur support team is growing from 4 to 9 people and Helpwave wants a seat license for each one. Does anyone know a simple help desk with flat pricing? We would switch this month if it handles shared inboxes well.",
"title": "Looking for a help desk tool that does not charge per agent",
"upvotes": 48,
"url": "https://www.reddit.com/r/sysadmin/comments/1p3k9aq/looking_for_a_help_desk_tool_that_does_not/",
"views": null
},
"reason": "States a deadline, names the incumbent they are leaving and asks for a specific feature.",
"reply": null,
"score": 92,
"stage": "open",
"stageChangedAt": null,
"stageChangedBy": null,
"subredditRules": []
}highlight gives the start and end of keySentence inside post.text, counted in UTF-16 units like JavaScript strings. It is null when the sentence can't be found in the text. author.email is filled only when an X author put an address in their public bio, so Reddit authors never have one. reply stays null until someone saves a link to the reply they posted.
Update a match
PATCH /v1/matches/{id} takes either a stage or a feedback, never both.
curl -X PATCH "https://api.hearbuyers.com/v1/matches/MATCH_ID" \
-H "Authorization: Bearer hb_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"stage": "replied"}'{
"id": "84dab689-a674-4872-ad0f-821dcb1a4866",
"stage": "replied"
}Send feedback to mark a match as not relevant. This closes the match as not_a_fit and teaches the scorer, so similar posts score lower in later scans. The reasons are not_a_buyer, wrong_topic, self_promo, vendor and other, and note is optional.
curl -X PATCH "https://api.hearbuyers.com/v1/matches/MATCH_ID" \
-H "Authorization: Bearer hb_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"feedback": "self_promo", "note": "A vendor posting about their own tool"}'{
"id": "9f941caa-9664-4142-b704-c34c50690514",
"reason": "self_promo",
"stage": "not_a_fit"
}Moving a match to any stage other than not_a_fit undoes an earlier lesson. Every change fires a match.stage_changed webhook.
Draft a reply, DM or email
POST /v1/matches/{id}/drafts writes a fresh draft for the match and answers with the draft of the kind you ask for: reply, dm or email. A reply or email call asks the model again and replaces the unapproved reply and email drafts on that match. A dm call writes only the DM and leaves the others alone. Drafts you approved in the app are kept, and an approved DM comes back unchanged. The answer is the draft, in the same shape as the entries of drafts on a match.
A match can't always have every kind:
| Kind | A match has it when |
|---|---|
reply | Always. It is the public reply to the post |
dm | Always. On X it is a direct message; on Reddit, a short private message the person sends themselves |
email | author.email is filled, which only happens for an X author who put an address in their public bio. Reddit matches never have one |
Read author.email on the match before you ask for an email. Without one, the call answers 502 draft_failed every time, and asking again only runs another model call.
curl -X POST "https://api.hearbuyers.com/v1/matches/MATCH_ID/drafts" \
-H "Authorization: Bearer hb_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"kind": "reply"}'{
"id": "5fb678f4-15fa-4971-904b-ed8ff69cfd78",
"kind": "reply",
"subject": "",
"body": "Flat pricing and shared inboxes are the two things we built Acme Helpdesk around. Happy to show you how a 9 person team would set it up, no seat fees.",
"status": "draft",
"approvedBy": null,
"approvedAt": null,
"openUrl": "https://www.reddit.com/r/sysadmin/comments/1p3k9aq/looking_for_a_help_desk_tool_that_does_not/"
}openUrl is where a person pastes or sends the draft: the post for a reply, the author's profile for a DM, and mailto: plus the author's address for an email. Nothing is posted for you. Drafting waits on a language model, so give the request a generous timeout. If the model call fails for a kind the match can have, the call answers 502 draft_failed and you can try again after a short pause.
Listeners
A listener is one thing the project watches: a keyword list, a subreddit, an X account, mentions of an X account, replies to one tweet, one Reddit thread, or a competitor. GET /v1/listeners returns them with the plan's usage.
{
"limit": null,
"listeners": [
{
"id": "63f962b5-4d1b-4d7e-933c-e9e2712f4f6b",
"type": "keywords",
"name": "help desk per agent pricing +1 more",
"sources": [
"reddit",
"x"
],
"terms": [
"help desk per agent pricing",
"switching from Helpwave"
],
"target": "",
"excludeWords": [
"hiring"
],
"includeComments": true,
"active": true,
"ended": false,
"lastScannedAt": null,
"createdAt": "2026-11-13T14:46:21.667554Z",
"matchesThisWeek": 0
}
],
"plan": "unlimited",
"usage": {
"listeners": {
"max": null,
"used": 1
},
"phrases": {
"max": null,
"used": 2
}
},
"used": {
"keywords": 1
}
}limit and max are null when the plan has no cap. POST /v1/listeners adds one and asks for a scan.
| Field | Meaning |
|---|---|
type | keywords, subreddit, x_account, x_mentions, tweet_replies, reddit_thread or competitor |
name | Optional. Made from the terms or target when left out |
sources | x, reddit or both. Only keyword and competitor listeners need it |
terms | Phrases for a keyword listener, or words to narrow a subreddit |
target | The subreddit, X handle, tweet or thread link, or competitor name |
excludeWords | Posts with these words are skipped |
curl -X POST "https://api.hearbuyers.com/v1/listeners" \
-H "Authorization: Bearer hb_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "keywords", "sources": ["reddit", "x"], "terms": ["help desk per agent pricing", "switching from Helpwave"], "excludeWords": ["hiring"]}'{
"listener": {
"id": "63f962b5-4d1b-4d7e-933c-e9e2712f4f6b",
"type": "keywords",
"name": "help desk per agent pricing +1 more",
"sources": [
"reddit",
"x"
],
"terms": [
"help desk per agent pricing",
"switching from Helpwave"
],
"target": "",
"excludeWords": [
"hiring"
],
"includeComments": true,
"active": true,
"ended": false,
"lastScannedAt": null,
"createdAt": "2026-11-13T14:46:21.667554Z",
"matchesThisWeek": 0
}
}The answer holds the listener and, when a scan started, its scanId. When none started, scanBlocked says why. DELETE /v1/listeners/{id} removes a listener and answers 204 with no body. Matches it already found stay. A tweet-replies listener runs for 14 days, then shows ended: true.
Leads
GET /v1/leads groups matches by author, so you see people instead of posts. Each row is a person's strongest match at or above the threshold, strongest first. Filter with platform (x or reddit) and q, which searches handles and names.
curl "https://api.hearbuyers.com/v1/leads?platform=reddit&limit=1" \
-H "Authorization: Bearer hb_live_YOUR_KEY"{
"leads": [
{
"key": "reddit:northwind_ops",
"author": "northwind_ops",
"name": "",
"platform": "reddit",
"profileUrl": "https://www.reddit.com/user/northwind_ops",
"matches": 1,
"bestScore": 92,
"bestMatchId": "84dab689-a674-4872-ad0f-821dcb1a4866",
"lastSeenAt": "2026-11-13T11:46:01.967311Z",
"sample": {
"quote": "We would switch this month if it handles shared inboxes well.",
"url": "https://www.reddit.com/r/sysadmin/comments/1p3k9aq/looking_for_a_help_desk_tool_that_does_not/"
}
}
],
"total": 2
}key is the platform and lowercase handle. matches counts how many of their posts matched, and bestMatchId is the one to open with GET /v1/matches/{id}.
Brand signals
GET /v1/brand-signals returns every post that names your brand or a competitor, whether or not the author shows buying intent. This is the social listening side of the API: share of voice and sentiment across Reddit and X. Parameters are days (1 to 365, default 30), brand, sentiment (positive, neutral or negative), limit and offset.
curl "https://api.hearbuyers.com/v1/brand-signals?days=30&brand=Helpwave&sentiment=negative" \
-H "Authorization: Bearer hb_live_YOUR_KEY"{
"brands": [
{
"name": "Acme Helpdesk",
"isYou": true,
"mentions": 1,
"share": 0.333,
"positive": 0,
"neutral": 1,
"negative": 0
},
{
"name": "Helpwave",
"isYou": false,
"mentions": 2,
"share": 0.667,
"positive": 0,
"neutral": 0,
"negative": 2
}
],
"mentions": [
{
"author": "northwind_ops",
"brand": "Helpwave",
"hidden": false,
"id": "1f2a5930-5e90-43b1-98f2-e4e98cb2ca2d",
"platform": "reddit",
"postedAt": "2026-11-13T11:46:01.962518Z",
"sentiment": "negative",
"text": "Our support team is growing from 4 to 9 people and Helpwave wants a seat license for each one. Does anyone know a simple help desk with flat pricing? We would switch this month if it handles shared inboxes well.",
"title": "Looking for a help desk tool that does not charge per agent",
"url": "https://www.reddit.com/r/sysadmin/comments/1p3k9aq/looking_for_a_help_desk_tool_that_does_not/"
},
{
"author": "tidebook_maya",
"brand": "Helpwave",
"hidden": false,
"id": "453fbd10-ecf5-489b-a3d7-0f17cfbdc5b1",
"platform": "x",
"postedAt": "2026-11-13T05:46:01.962518Z",
"sentiment": "negative",
"text": "Anyone switched off Helpwave recently? Our ticket volume doubled and the bill followed. Need something that routes email and chat into one queue.",
"title": "",
"url": "https://x.com/tidebook_maya/status/1857342198836412416"
}
],
"total": 2
}brands lists every brand you configured, yours first, with zero mentions when nobody wrote about it. share is a number from 0 to 1 and covers all mentions in the window, not just the filtered ones. Mentions you hid in the app are left out.
Overview
GET /v1/overview?days=7 gives the numbers behind the app's overview page: what was found, replied to and won, and what is waiting. days runs from 1 to 365, and on Pro it stops at the 180 days of history.
curl "https://api.hearbuyers.com/v1/overview?days=7" \
-H "Authorization: Bearer hb_live_YOUR_KEY"{
"daily": [
{
"date": "2026-11-07",
"found": 0,
"replied": 0
},
{
"date": "2026-11-08",
"found": 0,
"replied": 0
},
{
"date": "2026-11-09",
"found": 1,
"replied": 0
},
{
"date": "2026-11-10",
"found": 0,
"replied": 1
},
{
"date": "2026-11-11",
"found": 0,
"replied": 0
},
{
"date": "2026-11-12",
"found": 0,
"replied": 0
},
{
"date": "2026-11-13",
"found": 2,
"replied": 0
}
],
"days": 7,
"found": {
"reddit": 2,
"total": 3,
"x": 1
},
"lastScanAt": null,
"replied": 1,
"stillUp": 0,
"waiting": {
"approvedNotPosted": 0,
"newLeads": 3,
"open": 2
},
"won": 0
}stillUp counts saved replies that were still live at the last check. waiting.approvedNotPosted counts approved drafts on matches that still have no saved reply link, and waiting.newLeads counts authors first seen in the last 7 days.
Errors
Errors come back as JSON with an HTTP status. Most carry a code you can branch on and a message you can show.
| Status | Code | When |
|---|---|---|
| 400 | bad_view, bad_since, bad_days, bad_patch, bad_kind, bad_platform, bad_sentiment | A parameter is invalid. The message says which |
| 401 | unauthorized | The key is missing, malformed, wrong or revoked |
| 402 | plan_inactive | The project has no live plan |
| 402 | plan_limit | A listener or phrase over the plan's limit. The body has limit, used and max |
| 404 | none | The match or listener doesn't exist in this project |
| 429 | rate_limited | Over the per-minute limit. Wait for Retry-After |
| 502 | draft_failed | The model call failed, or the match can't have the kind you asked for, which only happens with an email when author.email is empty |
A 401 looks like this:
{"code":"unauthorized","error":"unauthorized","message":"This API key is not valid, or it was revoked."}A few older errors are {"error": "<message>"} with no code, like the 404 above, so check the HTTP status first. Retry 429 after the Retry-After pause. Retry a 502 only when the match can have the kind you asked for: an email without author.email fails the same way every time. Don't retry 400, 401, 402 or 404 either. The same request will fail again.
OpenAPI spec
The spec is at https://api.hearbuyers.com/v1/openapi.json and needs no key. Feed it to a client generator or an API tool. It lists the parameters and the core response fields. Responses can carry more, so ignore fields you don't recognise.
Questions about the social listening API
Is there a free tier?
No. The API is included in both plans, Pro and Ultra, at no extra charge, and your first subscription starts with a 7-day trial. See pricing.
Can the API post a reply for me?
No endpoint posts to Reddit or X. You can ask for a draft, then send it yourself or hand it to a person.
Does a key see my other projects?
No. A key belongs to one project, so if you run several, make a key in each.
What happens to my keys if I cancel?
They stay, but every call answers 402 plan_inactive until the project has a live plan again.
How fresh is the data?
A call returns what the last scans found. Pro scans every 60 minutes and Ultra every 15, and lastScanAt on the overview tells you when the last one finished. To hear about a match the moment it is found, use a webhook.
Can I use it with an AI agent?
Yes. Every endpoint here is also an MCP tool, so Claude or Cursor can use the same key. See the MCP server docs.
Get an API key
Keys are on your project's API page. The API, the MCP server and webhooks come with Pro and Ultra, so start the 7-day trial first. Pro allows 60 requests a minute per key, and Ultra allows 300.