> **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):** <https://www.socialfetch.dev/docs/tools/listening/your-first-topic>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/docs/tools/listening/your-first-topic.mdx>

## 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:** <https://www.socialfetch.dev/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`).

---
# Your first Listening topic (https://www.socialfetch.dev/docs/tools/listening/your-first-topic)

This guide takes you from a few words to a **topic** that keeps listening. It uses a brand, *Gymshark*, but anything works: a product, a person, a campaign or a topic.

## 1. Open Listening

1. In the [Social Fetch app](https://app.socialfetch.dev), open **Tools** and choose **Listening**.
2. Click **New topic**.

## 2. Say what to listen for

1. Under **Words or a query**, type `Gymshark`.
2. Wait a moment. Under the box, it reads your query back in plain words ("Finds posts that mention "gymshark"") and shows a logo for each platform it can search, with **Up to N credits**: the most this preview can cost.

Not sure how to write it? Click **Describe it** and say what you want in plain words, such as *complaints about Gymshark's sizing or delivery*, then **Write the query**. It's free, and nothing is searched until you preview. Or start from one of the templates under **Start from**. [Write your query](/docs/tools/listening/write-your-query) explains phrases, OR, leaving words out and importing from another tool.

  A platform logo with an amber dot can search only part of your query. That's normal for most platforms: they search your terms, and every post they find is then checked against the whole query. Click **Up to N credits** to see how each platform searches it.

## 3. Choose the options (optional)

Click **Options** to see:

* **Spend**: the most credits this preview may use. 50 by default. A higher limit reads further back.
* **Leave out**: **Job ads**, **Giveaways and contests** and **Crypto promotion and scams**. Posts like these are dropped after the search, so they don't change the cost.
* **Sentiment**: positive, neutral or negative for each post, 1 credit per 10 posts, on top.
* **Insights**: sets aside posts that aren't about it, and flags what needs a reply or could hurt you, 1 credit per 10 posts, on top. Turning it on asks for **About**: the name and what it is, such as *Gymshark, the UK gymwear brand*, so it can tell the brand from the word. You can also ask up to three yes/no questions of your own, such as *Does the post mention sizing?*

## 4. Preview it

1. Click **Preview posts**. It searches every platform it can, which can take up to a minute.
2. Read the summary: how many posts it found, on which platforms, and what it cost. Unused credits aren't charged.
3. Scroll the posts, newest first. Use the platform tabs, **Most reach (estimated)** and the sentiment and insights filters to narrow them. Under **Where it's said**, each platform says how far its search got.

[Read your results](/docs/tools/listening/read-your-results) explains every part of the preview.

If the posts aren't what you meant, change the query and preview again. A query you've already previewed with the same settings isn't charged twice.

## 5. Keep listening

1. Click **Keep listening** (in the preview's summary, or **Keep listening…** under the query).
2. In the dialog:
   * **Name**: what to call the topic.
   * **How often**: from **Every 15 minutes** to **Every week**. **Every 6 hours** is the default.
   * **up to N credits a run**: the most each run may spend. Under it, **At most N credits a month** shows the most a month of runs can cost.
   * **Leave out**, **Sentiment** and **Insights** start as you set them for the preview.
3. Optionally, open **More** for an **Alert** (when it finds a number of posts in an hour or a day), a daily or weekly **Briefing**, a **Webhook**, and a **Monthly cap** on credits.
4. Click **Save and run now**.

The topic opens. Its first run starts straight away; **Running now. Its matches appear here when it finishes.** After that it runs on its schedule, and each run keeps only posts it hasn't seen before.

## 6. Come back to it

Your topics are listed on the **Listening** page, each with its posts over the last 14 days and anything that needs attention. A topic's page has:

* what needs attention: spikes, volume alerts, and, with insights, posts that need a reply or are a risk;
* **Posts per day**, **Where it's said** and **Loudest voices** (click one to see their posts);
* the **Posts** it kept and its **Runs**;
* **Download**, **Settings**, **Run now** and, under **⋯**, **Pause** and **Delete…**.

- [Write your query](/docs/tools/listening/write-your-query) — Get exactly the posts you mean.

- [Read your results](/docs/tools/listening/read-your-results) — What each part of the preview and a topic's page means.

- [Costs and limits](/docs/tools/listening/costs-and-limits) — What uses credits, and how to keep a topic's spend down.