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

# Usage and Budgets

> Track Managed Research spend, budget caps, and hard-stop behavior.

Managed Research exposes usage and budget state through MCP, Python, and the UI.

## Plan and included usage

Managed Research separates the commercial plan from Beta Access.

| Surface            | What it includes                                                         |
| ------------------ | ------------------------------------------------------------------------ |
| Free               | One-time credits, `lite`, `directed_effort`, standard model access.      |
| Free + Beta Access | Free plus `open_ended_discovery`, `heavy`, and all-model access.         |
| Pro                | Monthly included usage, the paid GA model bundle, and higher run limits. |
| Pro + Beta Access  | Pro plus `open_ended_discovery`, `heavy`, and all-model access.          |
| Team               | 10x Pro included usage and run limits at 8x the Pro monthly price.       |
| Team + Beta Access | Team plus `open_ended_discovery`, `heavy`, and all-model access.         |

The June launch promo plan is `free_launch`: \$500 of Managed Research usage,
up to 2 concurrent active runs, and no self-serve scheduled projects. If you
need recurring or scheduled work, contact Synth so we can scope it against your
plan, Beta Access state, and resource limits.

Use `smr_get_billing_entitlements` to inspect the authoritative entitlement
snapshot for an organization. Usage details may show resource buckets such as
`agent_codex`, `openrouter`, `tinker`, and `sandbox`; pricing headlines roll
these into included Managed Research usage.

## Usage reads

Use usage reads to inspect month-to-date totals, recent totals, per-run spend, and budget state.

MCP tools:

* `smr_get_billing_entitlements`
* `smr_get_run_usage`
* `smr_get_run_resource_limits`
* `smr_get_run_progress_toward_resource_limits`
* `smr_get_project_usage`
* `smr_get_project_resource_limits`
* `smr_get_project_progress_toward_resource_limits`
* `smr_list_runs`

## Budget controls

Budgets can stop the current run or block new runs.

| Limit               | Behavior                                                             |
| ------------------- | -------------------------------------------------------------------- |
| `run_usd_cents`     | Stops the current run and marks the stop reason as budget exhausted. |
| `monthly_usd_cents` | Blocks additional run triggers after the cap is reached.             |
| `timebox_seconds`   | Stops a run on timeout even if budget remains.                       |

Resource limits expose the same state as first-class run and project nouns:

| Surface        | What to read                                                                         |
| -------------- | ------------------------------------------------------------------------------------ |
| Run limits     | `smr_get_run_resource_limits`, `smr_get_run_progress_toward_resource_limits`         |
| Project limits | `smr_get_project_resource_limits`, `smr_get_project_progress_toward_resource_limits` |
| Usage rollups  | `smr_get_run_usage`, `smr_get_project_usage`, `smr_get_billing_entitlements`         |

Progress responses include configured caps, current usage, remaining amount,
state, active blockers, and whether extension requests are allowed.

## Unblocking work

When a spend limit blocks a run or project, request an extension with
`smr_request_resource_limit_extension` or the matching Python SDK helper.

Extensions can set a new absolute USD limit or add USD budget to the current
limit. Callers can also ask Managed Research to resolve matching blockers and
resume the blocked run or project after the extension is accepted.

Orchestrators should ration before a hard block whenever progress is high:
reduce fanout, choose a cheaper model, summarize context, or request an
extension early.

## Provider usage

Provider bindings and model choices influence usage. Public examples use:

```python theme={null}
providers=[{"provider": "openrouter"}]
```

Backend preflight remains authoritative for provider availability, credentials, and budget blockers.

## Cost visibility

Evidence and usage should be read together. A useful run handoff includes:

* final state and stop reason
* task and actor counts
* artifact manifest
* report or PR summary
* provider/model choices
* usage and budget status