> For the complete documentation index, see [llms.txt](https://mcp-docs.nichefire.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mcp-docs.nichefire.com/tools/firesearch/execute-search.md).

# Execute Search

Run a live trend-research query and get back ranked results.

### `execute_search`

### What it does

Searches public sources — news, social media, and the web — for trends, themes, and topics related to your query, and returns a ranked list of results along with your current usage. It reads the open web at the moment you ask, not your organization's saved data.

### When to use it

Whenever you need up-to-date information on:

* Emerging or recent trends
* Market research
* Consumer behavior
* News momentum
* Social media insights
* Competitive analysis

This is also the natural starting point for deeper work: run a search first, then pass a result you care about to [`analyze_trend`](/tools/firesearch/analyze-trends.md) for the in-depth view.

### Parameters

| Parameter      | Required | Description                                                                                             |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `prompt`       | Yes      | The topic to research, in natural language.                                                             |
| `researchMode` | No       | `instant` (default) for a responsive, interactive answer, or `thinking` for an extended, in-depth pass. |

**Keep your prompt specific**— for example, `"resale sneaker market"` or `"AI coding agents adoption"` — rather than a multi-sentence brief. A focused phrase produces sharper results than a paragraph of context.

**On `researchMode`:** `thinking` explores more ground and takes noticeably longer. Inside ChatGPT, searches usually run in `instant` mode to keep replies responsive; other clients honour both.

### Quota

Each call consumes **one unit** of your organization's shared search quota. The pool is shared across everyone in your organization, so avoid unnecessary repeat searches.

Running several searches in parallel — different angles on the same topic — can improve coverage, but each one spends another unit. Check your remaining balance with [`get_usage`](/tools/get-usage.md) first, and if you are an agent acting for someone else, ask them before fanning out.

If a search fails for an internal reason, the unit is refunded.

[Quota](/errors-and-limits/quota.md)

### Example request

```json
{ "prompt": "cold brew coffee growth", "researchMode": "thinking" }
```

### Example response

```json
{
  "data": [
    {
      "title": "Ready-to-drink cold brew moves into convenience retail",
      "description": "Shelf space for canned cold brew is expanding beyond specialty grocers, with regional roasters launching single-serve formats aimed at commuters.",
      "date": "2026-07-18",
      "relevancy_score": 93,
      "platforms": ["News", "Reddit", "X"],
      "sources": [
        "https://example.com/cold-brew-convenience-retail",
        "https://example.com/single-serve-launches"
      ]
    },
    {
      "title": "Nitro cold brew becomes a default menu item in independent cafés",
      "description": "Independent shops are adding nitro taps as a margin play, and customers increasingly expect it alongside standard iced options.",
      "date": "2026-07-11",
      "relevancy_score": 87,
      "platforms": ["Instagram", "News"],
      "sources": ["https://example.com/nitro-taps-independents"]
    }
  ],
  "usage": {
    "rate_limit": { "limit": 60, "remaining": 58, "reset_at": "2026-07-23T14:05:00Z", "window_seconds": 60 },
    "quota": { "limit": 1000, "used": 2, "remaining": 998 }
  }
}
```

#### Reading the payload

| Field                    | What it holds                                               |
| ------------------------ | ----------------------------------------------------------- |
| `data[]`                 | The trends found, ordered by relevance.                     |
| `data[].title`           | The trend, stated as a headline.                            |
| `data[].description`     | What is happening and why it matters, in a sentence or two. |
| `data[].date`            | The date the trend was observed.                            |
| `data[].relevancy_score` | How closely the trend matches your prompt, from 0 to 100.   |
| `data[].platforms`       | Where the trend was seen — news, social platforms, forums.  |
| `data[].sources`         | Links the trend was drawn from.                             |
| `usage`                  | Your rate limit and quota after this call.                  |
| `reasoning`              | Present **only when no trends were found** — see below.     |

Every item carries the `sources` it came from, so claims can be traced back and cited rather than taken on trust.

#### When nothing is found

A search that surfaces no trends still succeeds: `data` comes back empty and an extra `reasoning` block explains why, so you can adjust the prompt instead of guessing.

```json
{
  "data": [],
  "reasoning": {
    "summary": "No distinct trends emerged for this phrasing — coverage was thin and mostly duplicated.",
    "prompt": "cold brew coffee growth",
    "keywords": ["cold brew", "rtd coffee"],
    "platforms": ["News", "Reddit"],
    "diagnostics": [
      { "platform": "Reddit", "fetchedItems": 4, "generatedTrendBlocks": 0, "reason": "Not enough distinct discussion to form a trend" }
    ]
  },
  "usage": {
    "rate_limit": { "limit": 60, "remaining": 57, "reset_at": "2026-07-23T14:05:00Z", "window_seconds": 60 },
    "quota": { "limit": 1000, "used": 3, "remaining": 997 }
  }
}
```

`summary` is the short explanation; `diagnostics` breaks it down per platform, showing how much material was found and why it did not amount to a trend. A narrower or more concrete prompt is usually the fix.