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

# Credits and usage

> What each MCP tool costs, why failed work is free, and how to read the usage object your agent gets back on every call.

Agent calls draw from the same credit wallet as everything else in Titan. There is no separate agent plan and no separate meter.

The rule is simple: **you pay for successful delivery**. Work that fails to deliver a record does not consume credits.

## Cost per tool

| Tool                    | Unit       | Cost                                     |
| ----------------------- | ---------- | ---------------------------------------- |
| `titan_search`          | Per run    | 1 credit, regardless of `max_results`    |
| `titan_fetch`           | Per page   | 1 credit per successfully extracted page |
| `titan_crawl` (`map`)   | Per URL    | 1 credit per URL delivered               |
| `titan_crawl` (`crawl`) | Per page   | 1 credit per page extracted              |
| `titan_run_template`    | Per record | 1 credit per record delivered            |
| `titan_list_templates`  | —          | Free                                     |
| `titan_get_run`         | —          | Free                                     |

<Note>
  Search bills per **run**, not per result. Asking for 100 results costs the same as asking for 10, so request what you will actually use and let cost follow your reading, not your ambition.
</Note>

## What is free

None of these consume credits:

* Validation failures — a bad parameter, an oversized limit, a malformed URL
* Authorization failures — a missing scope or an invalid key
* Insufficient credits — the preflight check rejects before any work begins
* Rejected URLs — anything blocked by [URL safety](/docs/mcp/limits-and-safety)
* Failed fetches — a URL that returns no record
* Blocked or rate-limited searches that deliver nothing
* Crawl records dropped for being cross-origin
* Polling with `titan_get_run` and browsing with `titan_list_templates`

Validation, auth, and credit checks all run **before** a Titan execution is created, so a rejected call leaves nothing behind to be charged for.

## One deliberate exception

A search that completes and confidently returns **zero organic results** is billable. It delivered a valid answer—that the query has no results—and that answer required real work.

A zero-result search caused by a block, a rate limit, a layout failure, or a timeout is **not** billed. The difference is whether the provider answered.

## Reading the usage object

Every run reports its own cost:

```json theme={null}
{
  "usage": {
    "backend_execution_id": "3c7d1a92-6f48-4b25-9e03-7d1a4c8b2f65",
    "billing_unit": "successful_delivery",
    "records_returned": 47,
    "records_available": 47,
    "credits_estimated": 50,
    "credits_consumed": 47,
    "billing_status": "billable",
    "failure_count": 3
  }
}
```

This was a 50-URL fetch. Three URLs failed, 47 succeeded, and 47 credits were charged.

| Field               | What it tells you                                                |
| ------------------- | ---------------------------------------------------------------- |
| `credits_estimated` | Upper bound computed before the run, from what you requested     |
| `credits_consumed`  | What was actually charged, based on delivery                     |
| `billing_status`    | `pending` while running, then `billable` or `not_billable`       |
| `records_returned`  | Records in this response                                         |
| `records_available` | Total the run produced—paginate if it exceeds `records_returned` |

While a run is in flight, only `credits_estimated` is meaningful and `billing_status` is `pending`. Both settle at terminal status.

## Credit preflight

Before starting work, Titan checks your balance against the **maximum estimate**—the worst case for what you asked for. If your balance is short, the call fails with:

```json theme={null}
{
  "code": "insufficient_credits",
  "message": "Insufficient credits for this request",
  "retryable": false
}
```

Titan does not silently downgrade a request to fit your balance. A 100-URL fetch either runs as a 100-URL fetch or fails cleanly. If you are near your limit, split the work into smaller calls yourself.

## Keeping agent spend predictable

| Practice                                   | Effect                                                                |
| ------------------------------------------ | --------------------------------------------------------------------- |
| Map before you crawl                       | Discover the inventory first, then extract only the pages that matter |
| Fetch selected URLs, do not crawl for them | Reading 5 known pages beats crawling 100 to find them                 |
| Set `max_pages` to what you need           | Crawl estimates scale with the cap you set                            |
| Use `idempotency_key` on retries           | A replayed run is free; a re-issued one is not                        |
| Scope keys tightly                         | An agent without `mcp:crawl` cannot run up a crawl bill               |

## Reconciling with billing

Because `run_id` is the Titan `execution_id`, agent spend reconciles like any other usage:

```bash theme={null}
# What one agent run cost
curl -sS "$TITAN_API_URL/api/v1/billing/usage/executions/$RUN_ID/spend-summary" \
  -H "Authorization: Bearer $TITAN_TOKEN"

# Ledger lines for a period
curl -sS "$TITAN_API_URL/api/v1/billing/ledger?from=2026-07-01&to=2026-07-31" \
  -H "Authorization: Bearer $TITAN_TOKEN"
```

Agent runs are attributable to their [agentic task](/docs/about-platform/tasks#agentic-tasks), so you can separate agent spend from the rest of your usage.

## Next steps

* [Credits and billing](/docs/about-platform/credits-and-billing) — the platform-wide model
* [Idempotency and retries](/docs/mcp/idempotency-and-retries) — retry without double-charging
* [Limits and safety](/docs/mcp/limits-and-safety) — the caps that bound cost