> **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`). --- # Sentiment and insights (https://www.socialfetch.dev/docs/tools/listening/sentiment-and-insights) {/* Prices follow QUERY_SENTIMENT_MENTIONS_PER_CREDIT and QUERY_INSIGHTS_MENTIONS_PER_CREDIT; accuracy figures from docs/plans/query-engine/research/s5-insights.md. Update them here if they change. */} **Sentiment** and **Insights** are options under **Options** when you preview, and in a topic's **Keep listening** dialog and **Settings**. Each reads every post the search finds, so you don't have to. They're estimates worked out from each post's text, so they can be wrong; you can correct them on a topic. ## Sentiment Each post gets **Positive**, **Neutral** or **Negative**: the feeling its author expresses. The results show the split as a bar, and each one is a filter. * **Cost:** 1 credit per 10 posts given a sentiment, rounded up per search or run, on top of the search's credits. * **On a topic**, each new post gets one, and a post is never labelled or charged again. To correct one, open the post's **⋯** menu and choose another label; your choice stays, and **Use the estimate** goes back to the estimate. ## Insights Turning on **Insights** asks one thing: **About**, the name and what it is, such as *Notion, the note-taking app* or *Jaguar, the car brand*. That's how it tells the brand from the word. Each post then gets: | Judgement | Shown as | What it means | | ------------------ | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Relevance** | **About {name}**, **In passing**, **Not about it** | Whether the post is about your topic, names it in passing while being about something else, or isn't about it at all: another meaning of the word, a tag on an unrelated post, or spam. | | **Kind** | **Complaint**, **Question**, **Praise**, **Buying**, **Promotion**, **News** | What the post does about your topic: complains or reports a problem, asks something, praises or recommends, wants to buy or just bought, promotes (an ad, a sponsored or affiliate post, a discount code, or the brand's own marketing), or reports news. Only on posts about the topic; otherwise no tag. | | **Needs reply** | **Needs reply** | The brand's team should probably reply: the author reports a problem or asks something they could answer. | | **Risk** | **Risk** | The post could hurt the brand's reputation if it spread: allegations, safety or security problems, outages, scandal, boycott calls, or a serious failure. Ordinary grumbles aren't risks. | | **Your questions** | ✓ and the question | Up to three yes/no questions of your own, such as *Does the post mention sizing or fit?* Each is a filter, with how many posts answered yes. | ### Nothing is hidden Posts **Not about it** move to their own view, with a count, one click away. Nothing is deleted, the API returns every post, and on a topic you can correct any post from its **⋯** menu by ticking or clearing **Not about it**. Your choice stays, and **Use the estimate** goes back to the estimate. With insights on, a topic's volume alerts, spikes and briefings count only posts about it, so a burst of posts using the word another way doesn't set them off. ### How accurate is it? We measured it on 782 real posts from six searches, chosen because their names have other meanings (Notion, Jaguar, Monzo, Gymshark, Mercadona and Social Fetch), plus 516 posts chosen to test replies and risks: * **Not about it** was right 95% of the time and found 81% of the posts that weren't about the brand. It wrongly set aside 2 of 428 posts that were about it. For "notion", where most posts used the ordinary word or a song title, it set aside 78 of 85 such posts, all correctly. * **Needs reply**: 69% of the posts it flagged needed one, and it found 74% of them. * **Risk**: 82% of the posts it flagged were risks, and it found 72% of them. * **Your questions**: most were right 9 times in 10 or more; recall depends on how literally a post says it. It errs towards showing: a post it isn't sure about stays under **About {name}**, often marked **In passing**. ### What it costs 1 credit per 10 posts given insights, rounded up per search or run, on top of the search's credits; the same price as sentiment. On a topic, each new post is judged once and never charged again. Posts with no text aren't judged or charged. ## When not every post gets one If your balance, your API key's monthly limit or a topic's monthly cap can't cover them, or they can't be worked out just then, some posts come back without a sentiment or insights, and those aren't charged. When more than a few are missing, it says so above the posts: **Insights on X of Y posts. The rest couldn't be given them this time, and weren't charged for it.** On a topic, posts found while the option was off have none. A workspace with **Zero retention** on can't use insights: posts aren't sent to be judged, and nothing is charged. - [Costs and limits](/docs/tools/listening/costs-and-limits) — Everything that uses credits. - [Troubleshooting](/docs/tools/listening/troubleshooting) — The messages Listening shows, and what to do about them.