> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nephia.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Explore

> One question, every Source, priced first. Search once without creating a Query.

A [Query](/introduction) keeps polling until you stop it. **Explore** asks once: every Source
you name runs its searches now, and the answer is the mentions they found. Nothing keeps
running afterwards, and nothing is charged again.

It is how you test an angle before you commit a Query to it: a competitor's name, a problem
phrase like "alternative to" or "anyone know a tool", the week of a launch. If the run comes
back empty, you have learned that for the price of one run instead of a month of checks.

## Price it, then run it

Both calls take the same body: the criteria every search inherits, and the Sources to ask,
each with up to three searches of its own.

```bash theme={null}
curl -X POST "https://api.nephia.cc/v1/explore/estimate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "globalCriteria": { "market": "global", "query": "alternative to stalkr" },
    "sources": [
      { "source": "reddit", "enabled": true },
      { "source": "hackernews", "enabled": true,
        "searches": [{ "label": "Ask HN", "overridesEnabled": true,
                       "overrides": { "query": "anyone know a tool" } }] }
    ]
  }'
```

`POST /v1/explore/estimate` calls no Source and charges nothing. It runs the run's own checks
and answers either `valid: false` with the refusal the run would give (its status, code and
the sentence naming the fix), or `valid: true` with:

* `estimate.total`: what the run costs if every search answers.
* `estimate.perLeg`: one entry per search, with its Source, its label and its credits.
* `estimate.balance`: what the account can spend right now.
* `estimateToken`: proof that this exact body was priced, valid 15 minutes.

Send the same body to `POST /v1/explore`, with the token in the `Nephia-Estimate-Token`
header. The run then refuses any other body. The header is optional with an API key, and
always required from the [MCP server](/mcp-server), so an agent never runs a question it did
not price.

## What a run answers

```json theme={null}
{
  "run": { "id": "6f0c…", "name": "alternative to stalkr" },
  "mentions": [ { "id": "…", "source": "hackernews", "title": "Ask HN: alternative to …", "run": { "id": "6f0c…", "name": "alternative to stalkr" }, "query": null } ],
  "outcomes": [
    { "source": "reddit", "label": "alternative to stalkr", "status": "ok", "rows": 0, "fetched": 25, "creditsCharged": 4 },
    { "source": "hackernews", "label": "Ask HN", "status": "ok", "rows": 1, "fetched": 1, "creditsCharged": 1 }
  ],
  "meta": { "credits_used": 5, "estimated_credits": 5, "duration_ms": 4120 }
}
```

`mentions` are the same [mentions](/api-reference/overview) every other read returns, newest
first by publication date, one per post even when two searches found it. They carry the run
and no Query, and no sentiment or intent: nothing has read them yet.

`outcomes` has one entry per search, and it is where the finding often is. `fetched` without
`rows` means the platform answered and your criteria kept nothing: the phrase is too narrow,
or nobody says it there. A `failed` search carries a `message` and is charged nothing.

## Read it again

A run is kept. Its mentions stay readable, for free, with the run id:

```bash theme={null}
curl "https://api.nephia.cc/v1/mentions?run=6f0c…&since=2026-09-01T00:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"
```

Read it there rather than running the same question twice. Widen `since` for an older run:
the default window is the last 24 hours. Runs also appear in the dashboard's Explore history.

## Limits and billing

* **Charged per search**, at each Source's explore rate, the moment it runs. Most Sources
  are a flat rate per search. **X is charged per tweet returned**: a base of 5 credits plus
  3 per tweet, so at most 65 for a page of 20, and 5 for a search that matches nothing. The
  estimate marks such a search `variable: true` and quotes the ceiling, so show it as "up
  to"; `outcomes[].creditsCharged` is what it really cost. A search that fails is not
  charged, and a run whose balance cannot cover the ceiling is refused before any search
  starts, with `402`.
* **At most 6 Sources and 3 searches per Source** in one run.
* **30 seconds.** A search still running then is reported `failed` with `timed out`. If its
  Source answers later, that charge shows in Spend without its mentions.
* **Five runs per five minutes** per account. The estimate is not limited this way.
* **AI answers cannot be explored**: an engine takes minutes to answer. Create a Query with
  the `ai_answers` Source instead.

Spend shows one line per search, grouped by run. See [Credits](/credits).