Credits and usage

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

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.

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
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:

{
  "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:

{
  "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:

# 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, so you can separate agent spend from the rest of your usage.

Next steps

Credits and billing — the platform-wide model
Idempotency and retries — retry without double-charging
Limits and safety — the caps that bound cost

Get started

Tool reference

How it works

Integration examples

Cost per tool

What is free

One deliberate exception

Reading the usage object

Credit preflight

Keeping agent spend predictable

Reconciling with billing

Next steps

​Cost per tool

​What is free

​One deliberate exception

​Reading the usage object

​Credit preflight

​Keeping agent spend predictable

​Reconciling with billing

​Next steps

Cost per tool

What is free

One deliberate exception

Reading the usage object

Credit preflight

Keeping agent spend predictable

Reconciling with billing

Next steps