> **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`). --- # Write your Listening query (https://www.socialfetch.dev/docs/tools/listening/write-your-query) {/* Syntax follows packages/query-language (parser.ts, ast.ts) and docs/plans/query-engine/language.md; limits from ast.ts. Update them here if they change. */} A query says what to listen for. The simplest is a word, such as `Gymshark`. As you type, Listening reads it back in plain words and shows which platforms can search it, so you can see what it will do before you spend anything. Checking a query is free. ## The basics | You type | It finds posts that… | | ---------------------------------------------- | ------------------------------------------------------------- | | `Gymshark` | say "gymshark", in any case | | `"Gymshark Vital"` | say that exact phrase | | `Gymshark leggings` or `Gymshark AND leggings` | say both, anywhere in the post | | `Gymshark OR YoungLA` | say either one | | `Gymshark -jobs` or `Gymshark NOT jobs` | say "gymshark" but not "jobs" | | `(Gymshark OR YoungLA) AND review` | group with brackets | | `#gymshark` | use the hashtag | | `@gymshark` | are by the account or mention it | | `gym*` | have a word starting with "gym"; `te?m` matches one character | | `lang:es Gymshark` | are in one language | `AND`, `OR` and `NOT` must be in capitals: a lower-case `or` is just a word. When a query mixes AND and OR at the same level, add brackets, because tools read that differently: it says so and won't search until you do. The **Query tips** link under an empty box shows these examples in the app. ## More precise queries | You type | It means | | --------------------------------------------- | ------------------------------------------------------------------ | | `"Gymshark sizing"~5` | all the words, in any order, with at most 5 other words among them | | `Gymshark NEAR/3 sizing` | within 3 words, either order; `ONEAR/3` keeps the order. Up to 50 | | `{AMP}` | exactly this case | | `title:(review)` / `text:(review)` | only in a post's title, or only in its text | | `country:gb` | posts from a country, where the platform says | | `platform:reddit` | posts on one platform | | `author:gymshark` / `mention:gymshark` | posts by an account, or mentioning it | | `type:reply` | a kind of post: `post`, `reply`, `repost`, `quote` or `comment` | | `verified:true` | by verified accounts | | `site:gymshark.com` / `url:gymshark.com/sale` | posts linking to a site or address | | `followers:>10000` | by accounts with more than 10,000 followers | | `likes:>=100`, `views:1000..50000` | posts with that many likes, views, comments or shares | A query can be up to 8,192 characters, with up to 500 terms. Some platforms don't return everything a query can check, such as a post's language. A post whose match depends on something missing still shows, marked **Might match**, with what couldn't be checked. See [Read your results](/docs/tools/listening/read-your-results#notes-on-a-post). ## Fewer posts that aren't about it A word like "notion", "jaguar" or "apple" has other meanings. To keep your results about the brand: * Pair the name with words only the brand's posts use: `Notion AND (app OR workspace OR template)`. * Leave out the meanings you don't want: `Jaguar -(animal OR zoo OR Jacksonville)`. * Use the brand's account or hashtag: `@NotionHQ OR #notionapp`. * Turn on **Insights**: it judges each post against what the topic is about and sets aside those that aren't, with a count, so nothing is lost. See [Sentiment and insights](/docs/tools/listening/sentiment-and-insights). Under **Options**, **Leave out** drops **Job ads**, **Giveaways and contests** and **Crypto promotion and scams**. Leave crypto off for a crypto brand: its own posts can read as promotion. ## Import a query from another tool 1. Choose **Paste from another tool**. 2. Paste the query from Brandwatch, Talkwalker, Meltwater, Onclusive or X advanced search. 3. **Written for** starts on **Detect it**, which works out which tool it's from and says so, such as "Read as Brandwatch, from NEAR/5f". If it guessed wrong, choose the tool. Each part of the query is translated **exactly**, as an **equivalent**, as an **approximation**, or not at all (**unsupported**), and the read-back says which. A part that can't be searched here is never silently dropped. There's also a free [Boolean query translator](/tools/boolean-query-translator), which converts a query between these tools without searching. ## Describe it and let AI write it 1. Click **Describe it**. 2. Say what you want to hear about in plain words, such as *people complaining about Monzo's app being down*. Up to 2,000 characters. Starter descriptions help if you're not sure where to begin. 3. Optionally, under **Show it real posts**, paste posts it **Should find** and posts it **Should leave out**, up to 5 of each. 4. Click **Write the query**. It writes the query and reads it back to you. If it isn't right, use **Refine with AI** (*also leave out job ads*), or edit the query yourself. Describe it is free. Nothing is searched until you preview. It also suggests what each platform should search when a name is ambiguous. ## Choose what each platform searches Click **Up to N credits** under the query to see how each platform searches it: * **X** and **Reddit** search the whole query at once. * **YouTube**, **TikTok** and **LinkedIn** search its terms, a search each. * **Instagram** searches each term as a hashtag. * **Threads** searches each term as plain words. * **Hacker News** searches titles, links and text. Every post found is then checked against your whole query, so a platform searching only your terms never adds posts that don't match. If the automatic searches aren't right for a platform, such as `#fetch` on Instagram for *Social Fetch*, edit them: remove one, add your own with **+ search** (or **+ #tag** on Instagram), or go back with **Use automatic**. A platform can have up to 10 searches of up to 200 characters. Your searches change only what's searched, never what counts as a match, and a topic keeps them. - [Your first topic](/docs/tools/listening/your-first-topic) — Preview it, then keep listening. - [Read your results](/docs/tools/listening/read-your-results) — What each part of the preview means.