> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). For curated orientation and workflow guidance, start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for agent onboarding and crawl rules, use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for the full endpoint list with links to pages like this one, use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt); for one platform's parameters and curls, use [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need structured JSON for tool registration. ## This page - **On-site (HTML):** - **Markdown (.mdx) URL:** ## API base URL and authentication - **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev` - **Authentication:** send `x-api-key: sfk_...` on `/v1/**` and `/v2/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route). - **OpenAPI JSON:** ## Recommended docs entrypoints (this site) - [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown). - [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope. - [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`. - [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — every operation with identifiers, pagination, outcomes, media download, credits, and its SDK method. Generated from OpenAPI, so use it for route selection instead of scanning individual pages. - [Recipes](https://www.socialfetch.dev/docs/recipes.mdx) — copyable workflows (brand monitoring, transcripts, Ad Library, creator scoring, Reddit research) with credit callouts and SDK examples. - [Integrations](https://www.socialfetch.dev/docs/integrations.mdx) — MCP for AI clients, n8n verified node, Apify Store Actors, Make custom app, SDK, and REST API connection paths. - [MCP product page](https://www.socialfetch.dev/mcp) — hosted MCP overview, OAuth, Skills install. - [MCP integration](https://www.socialfetch.dev/docs/integrations/mcp.mdx) — hosted `/mcp` server, OAuth, Cursor/VS Code/Claude install snippets, 910 endpoint tools, plus docs_search/docs_read for implementation help. - [n8n integration](https://www.socialfetch.dev/docs/integrations/n8n.mdx) — install `n8n-nodes-socialfetch`, credentials, and workflow examples. - [Apify integration](https://www.socialfetch.dev/docs/integrations/apify.mdx) — Store Actors under @social-fetch, PPE billing, dataset export, and quick start. - [Make integration](https://www.socialfetch.dev/docs/integrations/make.mdx) — custom app modules for Make scenarios, API key credentials, and module catalog. - [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt) — every documented operation with a direct link to that route's agent-readable markdown page (prefer this over parsing OpenAPI). - [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt) — per-platform endpoint files generated from OpenAPI (parameters, credits, curls). - [`/agents.txt`](https://www.socialfetch.dev/agents.txt) — agent crawl/onboarding file with capabilities, auth rules, and allowlist. - [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping. - [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages. - [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance. - [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs. - Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract. ## Markdown docs convention - Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`). - Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`). - Published blog posts use the same convention: `/blog/{slug}` → `/blog/{slug}.mdx`, or `Accept: text/markdown` on the HTML URL (`Vary: Accept`). --- # Listening (https://www.socialfetch.dev/docs/tools/listening) {/* Prices follow QUERY_SENTIMENT_MENTIONS_PER_CREDIT and QUERY_INSIGHTS_MENTIONS_PER_CREDIT in packages/public-api-contract. Update them here if they change. */} **Listening** finds what people say about a brand, product or topic across X, Reddit, YouTube, TikTok, LinkedIn, Instagram, Threads and Hacker News. You write what to listen for, as a few words or a Boolean query, preview the posts it finds, and then **keep listening**: it searches again on a schedule and keeps every new post, with alerts, a daily or weekly briefing and webhooks. It runs inside the [Social Fetch app](https://app.socialfetch.dev/tools/listening) on your credits. There's nothing to connect and no code to write. If you already use Brandwatch, Talkwalker, Meltwater or Onclusive, paste your query in and it's read as written. ## What you'll need * A **Social Fetch account**. [Sign up free](https://app.socialfetch.dev); new accounts get free credits to try things out. * **Credits**, the units Social Fetch charges in. Listening spends them on the searches it runs. See [Pricing](/pricing) for what credits cost, and [Credits](/docs/credits) for how they work. * What to listen for: a brand, product, person or topic, such as *Gymshark* or *"Monzo" outage*. * If you share a workspace, a role that can spend credits. Owners, admins and members can search and keep listening; members see only the topics they created; billing-only users can't open Listening. See [Teams and workspaces](/docs/teams). ## How it works 1. **You say what to listen for.** Type words or a query, paste one from another tool, or describe it and let AI write the query. As you type, it reads the query back in plain words and shows which platforms can search it. 2. **You preview it.** One search on every platform, up to a credit limit you set, returns the posts that match, newest first. Each post is checked against your whole query, wherever the platform could only search part of it. 3. **You keep listening.** Saved as a **topic**, it searches again on a schedule (every 15 minutes up to once a week) and keeps each new post once. Its page shows posts per day, where it's said, the loudest voices, and anything that needs attention. Two options read every post for you, each for a small extra charge: **Sentiment** (positive, neutral or negative) and **Insights**, which sets aside posts that aren't about your topic and flags what needs a reply or could hurt you. See [Sentiment and insights](/docs/tools/listening/sentiment-and-insights). ## What it costs Searches are charged at their normal credit price, and never more than the limit you set: **50 credits a preview** by default, and a **credits per run** limit for each topic (20 by default). Writing or checking a query is free, and so are filters, downloads, alerts, briefings and webhooks. Sentiment and insights each cost 1 credit per 10 posts they cover, on top. [Costs and limits](/docs/tools/listening/costs-and-limits) has the detail. ## Words you'll see | Word | What it means | | -------------------------- | ----------------------------------------------------------------------------------------------------- | | **Query** | What to listen for: words, phrases, hashtags and accounts, combined with AND, OR and NOT. | | **Preview** | One search now, to see what a query finds before you keep listening. | | **Topic** | A saved query that searches again on a schedule and keeps the posts it finds. | | **Run** | One scheduled (or **Run now**) search of a topic. | | **Spike** | Far more posts in a day than usual for the topic. | | **Briefing** | A daily or weekly summary on the topic's page and to its webhook. | | **Not about it** | A post that uses the word another way, or only tags it. Insights sets these aside, with a count. | | **Needs reply** / **Risk** | Posts insights flags: someone a brand's team should answer, or a post that could hurt its reputation. | ## Guides - [Your first topic](/docs/tools/listening/your-first-topic) — From a few words to a topic that keeps listening, step by step. - [Write your query](/docs/tools/listening/write-your-query) — Phrases, OR, leaving words out, importing from other tools, and Describe it. - [Read your results](/docs/tools/listening/read-your-results) — The preview, a topic's page, and what each note and filter means. - [Sentiment and insights](/docs/tools/listening/sentiment-and-insights) — Feelings, posts that aren't about it, and what needs a reply. - [Alerts and exports](/docs/tools/listening/alerts-and-exports) — Volume alerts, spikes, briefings, webhooks, downloads and the API. - [Costs and limits](/docs/tools/listening/costs-and-limits) — What uses credits, the limits you set, and what happens at a cap. ## Common questions ### Do I need to connect any accounts? No. Listening searches public posts. You don't log in to any platform or give it access to an account. ### Which platforms does it search? X, Reddit, YouTube, TikTok, LinkedIn, Instagram, Threads and Hacker News. X and Reddit search the whole query; the others search its terms (Instagram by hashtag), and every post found is then checked against the whole query. As you type, the platform logos show which can search all of it and which only part. Facebook isn't searched. ### Can I bring my query from Brandwatch, Talkwalker, Meltwater or Onclusive? Yes. Choose **Paste from another tool**, paste it, and it's detected and read as written, or pick the tool under **Written for**. Each part says whether it carried over exactly, as an equivalent, as an approximation, or not at all. X advanced search queries work too. See [Import a query](/docs/tools/listening/write-your-query#import-a-query-from-another-tool). ### How far back does it search? A preview and a topic's first run read each platform's newest posts, as far back as the credit limit allows: a higher limit reads further back. After that, each run searches from shortly before the last one, so it keeps what's new. Each post shows its age. ### Will it show posts that aren't about my brand? A keyword search finds everything that says the word: "notion" is also an ordinary word, and "jaguar" an animal and a football team. Make the query more specific (see [Write your query](/docs/tools/listening/write-your-query)), or turn on **Insights**, which sets those posts aside under **Not about it**, with a count, so you can still check them. ### How long are posts kept? A topic keeps each post it finds for a year. Deleting the topic deletes its posts. A workspace with **Zero retention** on can preview but can't keep listening, because a topic's job is to store what it finds. ### Can my team see the same topics? Topics belong to your workspace. Owners and admins see all of them; members see the ones they created. ### Is there an API? Yes. Everything here is in the API too: [search with a query](/docs/api/v1/query/search/post), and [saved queries](/docs/recipes/saved-queries) for topics, with webhooks. The app and the API share the same topics. - [Troubleshooting](/docs/tools/listening/troubleshooting) — The messages Listening shows, and what to do about them.