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

# Cost control

> Use live prices, representative pilots, and scoped billing evidence to control usage.

[Human guide: work with your agent →](https://deepline.com/docs/human/cost-control.md)

Estimate a bounded pilot, inspect its recorded usage, and decide whether the
full job fits the intended budget. Workspace balance is not a per-command bill.

## 1. Read the current controls

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline billing balance --json
deepline billing limit --json
```

The first reports workspace funds. The second reports the workspace monthly
usage cap. Neither is a dedicated spending limit for your current command.

For an authored Play, set `billing.maxCreditsPerRun` under the
[authoring contract](https://deepline.com/docs/sdk-v2/sdk-reference.md). To override that cap for one run,
pass `--max-credits`. The override can raise or lower the authored cap:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline plays run my.play.ts --max-credits 50
```

The API and SDK accept `maxCredits` on the run request. Child Plays share the
parent run's cap. Deepline refuses a call that would exceed it before provider
work starts. The run fails with the cap, spent credits, and refused call estimate.
Compute already used is still billed. A cap does not undo admitted work.

## 2. Inspect the priced operation

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline describe hunter_email_verifier --json
```

Use the actual tool ID selected for your route. Read its pricing unit,
credential state, required inputs, and result contract. Request-priced and
result-priced actions can have different miss costs.

For a composed Play, inspect the route and review every operation that can run.
An estimate describes the planned input mix. It is not a settled charge.

## 3. Run a representative pilot

Follow [Batch CSV enrichment](https://deepline.com/docs/sdk-v2/batch-csv.md) for record-safe selection.
Include the input conditions that affect coverage and cost.
Keep the run ID and direct tool execution IDs.

## 4. Read scoped usage

For a Play, use its run ID:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline billing usage --run-id <run-id> --json
```

For a direct tool execution, use its returned `job_id` or `next.billing` command:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline billing usage --request-id <job_id> --json
```

Follow returned pagination when reviewing recent-call pages. Keep pending,
unknown, and recorded final outcomes distinct. An absent amount is not zero.

> [!TIP]
>
> Your estimate uses accepted outputs and scoped, recorded usage. It does not
> attribute every workspace balance change to one pilot.

Other callers, top-ups, and concurrent runs can change the workspace balance.
Do not use balance subtraction as proof of one command's cost.

## 5. Review the scale decision

Report the route, representative sample, accepted results, misses, errors, and
recorded credits. Calculate credits per accepted result from comparable evidence.
Keep projections separate from actual charges.

For BYOK, include your provider-account costs separately when comparing total
workflow cost. Deepline exposes its applicable charges, not internal provider spend.

## 6. Change a cap only when intended

The following sets a workspace-wide monthly cap of 10,000 credits:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline billing set-limit 10000 --json
deepline billing limit --json
```

Choose the amount for your workspace. A cap can affect other users and jobs.
Removing it is also a workspace change:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline billing off
```

If funding or access blocks execution, inspect the returned reason and recovery
action. Do not silently switch to a different paid route.

Ask your agent to reconcile uncertain usage before repeating provider work.
See [tool recovery](https://deepline.com/docs/sdk-v2/tool-execution-recovery.md#billing-and-plays) for a lost response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.