> **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 troubleshooting (https://www.socialfetch.dev/docs/tools/listening/troubleshooting) ## Writing a query ### "This mixes AND and OR without brackets, and tools read that differently." Your query has AND and OR at the same level, such as `Gymshark leggings OR shorts`. Tools disagree on which goes first, so add brackets to say which you mean: `Gymshark (leggings OR shorts)`. ### "This closing bracket has no opening bracket." / "This bracket is never closed." The brackets don't pair up. Count them, or remove the extra one. ### "NOT needs something to exclude after it." `NOT` (or `-`) is at the end, or before a bracket that's empty. Put the word to leave out straight after it: `Gymshark -jobs`. ### "Wildcards go inside one word, such as run\* or te?m." A `*` or `?` can't stand alone or sit inside quotes. Attach it to a word. ### "NEAR can span at most 50 words." Use a number from 0 to 50 after `NEAR/`. ### "A hashtag is # followed by letters, digits or underscores." Remove spaces and punctuation from the hashtag: `#gymsharkwomen`, not `#gymshark women`. ### "Queries can be up to 8192 characters long…" The query is too long. Move long lists of words into fewer, broader terms, or split it into two topics. ### "That's a lot of checks in a minute. It reads it again in N seconds." Queries are checked as you type, up to a limit a minute. Wait, and it checks again on its own. ### "That doesn't say what to listen for. Name a brand, a product or a topic." **Describe it** needs something to listen for. Name the brand, product or subject, such as *complaints about Monzo's app*. ### A platform logo has an amber dot, or says it can't search it An amber dot means the platform searches only part of the query, usually its terms; every post it finds is still checked against the whole query. "Can't search it" means nothing in the query can be searched there, such as a query that's only a field the platform doesn't have. See [Choose what each platform searches](/docs/tools/listening/write-your-query#choose-what-each-platform-searches). ## Previews ### The preview found nothing on a platform Its note under **Where it's said** says why. **No mentions in the latest N posts.** means it read that many recent posts and none matched; try broader words, or raise **Spend** to read further back. **Reached your credit limit before finding any.** means its share of the limit ran out: raise **Spend**. ### Lots of posts aren't about my brand The name has other meanings. Make the query more specific, or turn on **Insights** with **About** set to the name and what it is. See [Fewer posts that aren't about it](/docs/tools/listening/write-your-query#fewer-posts-that-arent-about-it). ### "Might match: … so that part of the query wasn't checked." Your query checks something, such as a language, that the platform doesn't return for that post. The rest matched, so it's shown and marked. If you only want posts that certainly match, leave that part out of the query. ### "Ran out of time, so it may have missed some. What it found is shown." A preview has about a minute; that platform didn't finish. What it found is kept. Previewing again usually completes it. ### "The platform didn't answer just now. Preview again later." That platform failed this time, and wasn't charged. Preview again later. ### "The search couldn't be reached. Search again: if it already ran, you get its results without being charged again." The connection dropped. Search again: a preview that already ran returns its results, uncharged. ### "Your balance can't cover…" / **Buy credits** A search sets aside its whole limit while it runs. Lower **Spend** below your balance, or buy credits. See [Running out of credits](/docs/tools/listening/costs-and-limits#running-out-of-credits). ### "Your role can't spend the workspace's credits, so it can check and write queries but not search them." Your workspace role can't spend credits. Ask an owner or admin for a role that can. See [Teams and workspaces](/docs/teams). ## Topics ### "This workspace keeps no request content, so it can't save a query: a saved query keeps the posts it matches." Your workspace has **Zero retention** on, and a topic's job is to keep posts. You can still preview. To keep listening, turn **Zero retention** off on the app's [Settings](https://app.socialfetch.dev/settings) page. An existing topic pauses: *This workspace keeps no request content, so a saved query can't store its matches. Turn that off to resume it.* ### "This workspace already has 100 saved queries, the most it may have. Delete one first." A workspace can have 100 topics. Delete one you no longer need. ### The topic shows **Capped**: "This month's credit cap is spent: it runs again next month, or raise the cap." Its **Monthly cap** is used up. It runs again on the 1st (UTC). To run sooner, raise the cap (or empty it for no cap) in the topic's **Settings**. ### "Running it now could pass this month's credit cap of N: raise the cap to run it." **Run now** would take it past its cap. Wait for its next scheduled run next month, or raise the cap in **Settings**. ### The topic shows **Failing**: "Its last 5 runs failed. Resume it to try again." Five runs in a row failed, so it stopped. Its **Runs** tab says why each failed; the usual reason is **Not enough credits to run it.** Fix that (add credits), then click **Resume**. ### "Not enough credits to run it." Your balance couldn't cover the run's **credits per run** when it started. Add credits; the next run tries again. ### "It's paused: resume it first." Click **Resume** before **Run now**. ### "The API key it was created with no longer works. Save it again with a working key, or from the app." The topic was saved through the API with a key that's since been deleted, so it paused. Save it again from the app, or with a working key. ### "The API key it was created with has reached its monthly credit limit." The topic was saved through the API, and its runs count toward that key's monthly limit, which is used up. Raise the key's limit on [API keys](https://app.socialfetch.dev/api-keys), or save the topic again from the app. ### "Nothing yet: the first run is still searching." / "No posts matched yet." The first run takes up to about a minute after you save. After that, a topic with no posts simply hasn't heard anything new: each run searches what's new since the last one. ### I can't change the query or schedule in Settings **Settings** in the app changes the credits per run, monthly cap, briefing, alert, **Leave out**, sentiment and insights. To change the query or schedule, save a new topic with them (and delete the old one), or update it through the [saved queries API](/docs/recipes/saved-queries). ## Sentiment and insights ### "Insights on X of Y posts. The rest couldn't be given them this time, and weren't charged for it." Some posts couldn't be judged in time, or your balance, key limit or the topic's cap didn't cover them. Those posts weren't charged. The same goes for sentiment. On a topic, posts found while the option was off have none. ### "Insights aren't available with zero data retention…" A workspace with **Zero retention** on can't send posts to be judged. Nothing is charged. ### "Insights need to know what it's about" Fill in **About**: the name and what it is, such as *Gymshark, the UK gymwear brand*. ### A post is marked **Not about it** but it is about my brand On a topic, open the post's **⋯** menu and clear **Not about it**. Your choice stays, and the topic's counts and alerts follow it. In a preview, look under **Not about it** to check them. If you need help with something not listed here, [contact support](https://app.socialfetch.dev/support). - [Your first topic](/docs/tools/listening/your-first-topic) — Preview it, then keep listening. - [Costs and limits](/docs/tools/listening/costs-and-limits) — Everything that uses credits.