Skip to content

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.

Get an API key

Included with Pro and Ultra. Keys are made on your project's API page.

Make your first request

  1. Start a plan. The API comes with Pro and Ultra, and your first subscription has a 7-day trial.
  2. Open your project's API page in the app and create a key. Copy it right away. It is shown once.
  3. 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.

PlanRequests per minuteHistory the API can read
Pro60180 days of matches, leads and overview
Ultra300No 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.

ParameterWhat it does
stageopen (default), replied, won, not_a_fit, dismissed, closed (won, not a fit and dismissed together) or all
sourcex or reddit
minScoreLowest score to return, 0 to 100. Defaults to the project's threshold, which is 70 until you change it
sinceOnly matches found at or after this RFC 3339 time
limit1 to 100, default 50
cursorThe 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.

FieldMeaning
idThe match id, used by every other call
sourcex or reddit
communityThe subreddit, or empty for X
authorHandleWho wrote the post
postedAtWhen they posted it
scoreBuying intent from 0 to 100
intentactively_looking, comparing, complaining or just_curious
stageopen, replied, won, not_a_fit or dismissed
keySentenceThe sentence that matched, copied from the post
hasDraftWhether a drafted reply, DM or email exists
kindpost, comment or reply
listenerIdsThe listeners that found it
upvotes, commentCountReddit counts as of the last fetch, null when unknown
likes, repliesX counts as of the last fetch, null when unknown
authorAvatar, authorVerifiedX profile picture and verified badge
aboveThresholdWhether 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:

KindA match has it when
replyAlways. It is the public reply to the post
dmAlways. On X it is a direct message; on Reddit, a short private message the person sends themselves
emailauthor.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.

FieldMeaning
typekeywords, subreddit, x_account, x_mentions, tweet_replies, reddit_thread or competitor
nameOptional. Made from the terms or target when left out
sourcesx, reddit or both. Only keyword and competitor listeners need it
termsPhrases for a keyword listener, or words to narrow a subreddit
targetThe subreddit, X handle, tweet or thread link, or competitor name
excludeWordsPosts 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.

StatusCodeWhen
400bad_view, bad_since, bad_days, bad_patch, bad_kind, bad_platform, bad_sentimentA parameter is invalid. The message says which
401unauthorizedThe key is missing, malformed, wrong or revoked
402plan_inactiveThe project has no live plan
402plan_limitA listener or phrase over the plan's limit. The body has limit, used and max
404noneThe match or listener doesn't exist in this project
429rate_limitedOver the per-minute limit. Wait for Retry-After
502draft_failedThe 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.