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

# Five Nine Agent

> Live catalogs from the open web, under signed receipts.

Ask a natural-language question, or hand us a catalog URL. The Five Nine Agent drives
real browsers against real merchants and streams back attributed rows — each one tied
to the source it came from, under a signed per-source receipt. What you get is not a
one-shot extraction but a **session**: durable, replayable, and follow-up-able, with
per-decision provenance for every dollar spent.

## What makes this API different

We state the truth about every run, including the unflattering parts:

* **Delivered work is itemised, per source.** Each source pass that delivers ends in a
  receipt with the measured cost, the claim it makes, and the records behind it, and
  every row on `GET …/rows` names the receipt that paid for it. If a pass's cost basis
  is unavailable, it settles at **\$0**: only measured cost is billed. Two things are
  billed without a per-source receipt — the run's own orchestration spend, and passes
  that delivered nothing — so `spend_usd` and the ledger, not the receipts sum, are the
  complete account of a bill
  ([what a receipt covers](/guides/proposals#what-a-receipt-covers--and-what-it-does-not)).
* **Unchecked sources are stated.** If a run ends before every candidate merchant was
  dispatched, the terminal event lists them under `unchecked`. We never pretend
  coverage we didn't buy.
* \*\*Abstains are $0 outcomes, stated.** When the agent can't honestly deliver — the
  page isn't a catalog, the data is gated, the question has no purchasable entity — it
  says so and charges nothing for what it didn't do. A refusal to spend is a [$0 `abstained` run with the reasoning attached]\(/errors/declined\_to\_spend) (and
  `would_run: false` on the free estimate, before you commit), not a silent empty
  result.
* **You see why money moved.** The event stream carries every routing decision —
  dispatched, declined, and the reason — in the same stream as the rows.

## What a run costs, and how long it takes

Honest numbers from production, so you can design around them:

* A session fans out to several merchants and typically costs **low single-digit
  dollars** (\~\$0.50 per source pass). You set the ceiling: `max_spend_usd` is required
  on every spending call, and the run can never exceed it.
* A real run takes **tens of minutes, not seconds** — measured real sessions ran
  **11 to 68 minutes** end to end (single-merchant questions at the low end; runs
  that retried flaky sources at the high end), with first rows arriving in \~4–17
  minutes. Design for an asynchronous wait, not a request/response loop.
* The [quickstart](/quickstart) sequences around this: two instant, free calls first,
  then the real run with the wait announced.

## The three surfaces

| Surface        | Where                               | What                                                                                                                   |
| -------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| REST + SSE API | `https://api.fiveninelabs.com/v1`   | Sessions and receipts today — the [API reference](/api-reference) (extractions and monitors are planned, marked there) |
| Dashboard      | `https://platform.fiveninelabs.com` | Keys, usage, session forensics, playground                                                                             |
| MCP server     | `https://api.fiveninelabs.com/mcp`  | **Not yet available — planned.** The same sessions, as tools for your agent — [MCP setup](/guides/mcp)                 |

## The two ways in

* **Question-first — sessions.** `POST /v1/sessions` with a natural-language query.
  The agent resolves merchants, locates catalogs, dispatches passes, and adjudicates
  the answer. Follow up with free narrows and asks; a follow-up that costs money comes
  back as a [priced proposal](/guides/proposals), never a silent charge.
* **URL-first — extractions.** *Not yet available — planned.* Already know the
  catalog page? `POST /v1/extractions` will skip the fan-out entirely: one URL, one
  pass, one receipt, then [refresh and monitor it](/guides/refresh-and-monitors) at
  marginal cost. See [Extractions](/guides/extractions) for the contract it ships
  against; the [changelog](/changelog) will announce it.

## Stability, plainly

* The API is versioned by dated `fn-version` header with account pinning. Additive
  changes (new fields, new event phases, new endpoints) ship to every version;
  behavioral changes get a new date. Your client must tolerate unknown fields and
  unknown event phases — [unknown phases are liveness](/guides/events).
* Runs are retained **at least 90 days** — replayable and free to re-read for the whole
  window. On-request redaction (`DELETE /v1/sessions/{id}`, which will drop a run's data
  while the ledger skeleton survives for audit) is **planned, not served** — it answers
  `501 not_implemented` today. If you have a data-retention requirement, treat redaction
  as unavailable until the [changelog](/changelog) announces it.
* Every error is one envelope with a stable `code` and a `doc_url` that resolves to a
  page in [Errors](/errors). Program against `code`.