---
title: "Search"
description: "Search any term over the last 24 hours, 7 or 30 days without creating a keyword, with every result scored against your company."
canonical: https://docs.mentio.dev/guides/search
markdown: https://docs.mentio.dev/guides/search.mdx
---

# Search

Search any term over the last 24 hours, 7 or 30 days without creating a keyword, with every result scored against your company.

A search reads one term once, over a recent window, on every platform that can search back in time. Check a competitor, a launch or an idea before you track it.

Nothing is created: no keyword, no alerts.

## How a search works [#how-a-search-works]

1. You start it with a term and a window: the last `24h`, `7d` or `30d`.
2. Each platform is read once, at most 25 results a platform, newest first. A result holds the term as a phrase (written joined or as a hashtag counts).
3. Every result is scored for relevance, sentiment and intents against your [company profile](/how-it-works), as a mention would be.
4. When every platform has answered and every result is scored, the search is `done`.

Most searches finish in a minute or two. Results can be read while a search runs.

The results stay apart from your mentions. No alert, digest, report, count or mention cap sees them. A post you already track carries `alreadyInWorkspace: true`.

## Platforms [#platforms]

By default a search reads every platform that can search a term back in time:

| Platform                                                                             | Notes                                                      |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| Bluesky, Hacker News, GitHub, Stack Overflow, YouTube, X, LinkedIn, TikTok, Facebook | Up to 25 results each                                      |
| Reddit                                                                               | Posts and comments, 25 results in all                      |
| Instagram                                                                            | Reads at most its last 7 days, whatever the range          |
| DEV, News                                                                            | No search: reported as `skipped` with reason `unsupported` |

`platforms` narrows the list. Each entry of the search's `platforms` says its own `status` (`queued`, `running`, `done`, `skipped`, `failed`) and, when it read nothing, the `reason`:

| Reason             | Meaning                                          |
| ------------------ | ------------------------------------------------ |
| `unsupported`      | The platform has no term search                  |
| `credentials`      | The platform is not connected on this deployment |
| `budget`           | The platform's monthly vendor budget is spent    |
| `rate_limited`     | The platform kept refusing the read              |
| `error`, `timeout` | The read failed                                  |

## Cost [#cost]

A search costs $0.008 per scored result, the price of a mention, on its own line of the bill (`debit_searches` in the [ledger](/billing)). A result the classifier could not score is free.

Searches start with your first top-up: on the welcome credit alone the answer is `402 funding_required`.

Before a search starts, your balance must cover the most it can cost:

* 25 results for each platform read: $0.20 a platform, $2.20 for all eleven. That is `maxCostCents`.
* A search still running holds back what it can still cost from your next search until it finishes.
* Otherwise the answer is `402 insufficient_balance`.

`costCents` is what the search has cost so far.

A workspace can start 10 searches an hour (`429 rate_limited`, with `Retry-After`).

## Start a search [#start-a-search]

`kind` (`brand`, `competitor` or `topic`, the default) and `context` tell the classifier what the term is, as they do on a keyword.

```bash
curl -X POST https://api.mentio.dev/v1/searches \
  -H "Authorization: Bearer $MENTIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "term": "globex", "range": "30d", "kind": "competitor", "platforms": ["reddit", "hackernews", "linkedin"] }'
```

The answer is the search, `queued`, with its `id` (`srch_...`) and `maxCostCents`.

## Wait for it [#wait-for-it]

```bash
curl https://api.mentio.dev/v1/searches/srch_... \
  -H "Authorization: Bearer $MENTIO_API_KEY"
```

Poll every 10 to 20 seconds until `status` is `done`, or `failed` when no platform could be read. `stats` counts the results, the scored and the relevant ones.

## Read the results [#read-the-results]

```bash
curl "https://api.mentio.dev/v1/searches/srch_.../results?minRelevance=40&limit=25" \
  -H "Authorization: Bearer $MENTIO_API_KEY"
```

Each result has the mention's `post` and `author`, a `classification` (`null` while it waits for the classifier), `relevant` (scored 40 or more) and `alreadyInWorkspace`. Results come newest first, paged with `nextCursor`.

`GET /v1/searches` lists your searches, newest first. Searches and their results are kept 30 days.

## From an agent or the CLI [#from-an-agent-or-the-cli]

MCP has `start_search`, `get_search`, `list_search_results` and `list_searches`. The CLI has `mentio searches:create`, `searches:get`, `searches:results` and `searches:list`.

## When to track instead [#when-to-track-instead]

A search is a one-off look. To hear about a term as it is said, with alerts and digests, [create a keyword](/guides/keywords): its first 30 days come with it.