Usage, Plans, and Budgets

Track Managed Research plan state, included usage, flex credits, reset grants, promos, and budget caps.

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

Plan and included usage

Managed Research separates the commercial plan, included usage windows, flex-credit wallet, reset grants, and Beta Access.

Surface	What it includes
Free	Included Managed Research allowance, lite, directed_effort, and standard model access.
Standard	Paid included usage windows and the standard GA model bundle.
Max	Larger included usage windows and heavier organization usage.
Any plan + Beta Access	Adds open_ended_discovery, heavy, and all-model access when granted.

The active catalog currently uses Free / Standard / Max. Included usage is tracked in premium and value allowance windows that self-roll on a fixed grid; an owner-selected reset anchor can change the phase for an organization.

Flex-credit wallet balance, banked reset grants, and promo grants are shown separately. A reset grant is not a flex-credit balance. Private promos and make-good grants appear only when they are granted to the organization; public docs should not assume every account has one.

Use smr_get_billing_entitlements to inspect the authoritative entitlement snapshot for an organization. Use the Usage page or the billing SDK namespace to inspect the current plan, wallet, reset bank, promos, blocked reason, and next actions. 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.

Plan recovery

When included windows and flex credits are exhausted, the product should name the exhausted resource and at least one recovery path:

• wait for the next included-window reset
• use an approved banked reset grant when available
• reduce scope or choose a cheaper model/provider
• upgrade to a larger plan
• contact an organization owner or Synth operator for an approved grant

Flex-credit top-up checkout is not always available. Use the checkout UI only when the current billing snapshot exposes a matching checkout action.

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:

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