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

> How to set spending limits in Deepline CLI - session caps, monthly caps, and automatic sampling. Use it to understand tradeoffs and operating boundaries.

Three levers: session limits, monthly caps, and sampling.

## The short version

```bash theme={null}
# Cap this session at $10
deepline session limit --dollars 10

# Cap your account at 10,000 credits/month
deepline billing --set-monthly-limit 10000

# Check what you've spent
deepline session usage
```

That's it for most people. Keep reading if you want the details.

## Session limits

A session limit is a hard stop. Hit the limit, Deepline stops calling APIs. No warning.

```bash theme={null}
deepline session limit --dollars 10
```

Check where you stand:

```bash theme={null}
deepline session usage
```

```json theme={null}
{
  "session_id": "abc-123-def",
  "credits_used": 2.45,
  "cost_usd": 2.45,
  "dollar_limit": 10.0,
  "limit_reached": false
}
```

When `limit_reached` flips to `true`, you're done. Clear it with `deepline session limit --clear` if you want to keep going.

\$10-20 is usually enough for exploratory work.

## Monthly caps

Protects you from runaway automation. Forgot a cron job? Monthly cap saves you.

```bash theme={null}
deepline billing --set-monthly-limit 10000
```

Check the state with `deepline billing limit`. Turn it off with `deepline billing --off`.

When you hit the cap, all API calls stop until the next billing cycle. Account-wide, not per-session.

User-level caps are coming. Right now it's account-wide only.

## Automatic sampling

Deepline runs a sample before running your full list. Default behavior.

The exploratory phase tests 2-5 rows depending on list size. Usually costs 10-20 cents. We're checking what data is available, whether endpoints work with your input, and what quality looks like.

| List size | Sample rows | Typical cost |
| --------- | ----------- | ------------ |
| Under 50  | 2 rows      | 5-10 cents   |
| 50-500    | 3 rows      | 10-15 cents  |
| 500+      | 5 rows      | 15-20 cents  |

After the sample, you see results. Then you decide whether to continue.

Skip sampling with `--all` if you know what you're doing. Or pick your own sample size:

```bash theme={null}
# First 10 rows only
deepline enrich --input leads.csv --output enriched.csv --rows 0:10 --with '...'
```

## Why estimates look high

Estimates show worst-case. An estimate might say $50 when actual cost is $5.

Waterfalls short-circuit when a provider returns valid data. Most providers only charge on hits. Validation catches bad data early. The estimate assumes everything fails and retries. That rarely happens.

We err conservative so you never overspend unexpectedly. These estimates get better over time.

See an estimate that doesn't match reality? Run `deepline session send --current-session` to send us the session data. We use it to calibrate.

## Running your first enrichment

Set a limit:

```bash theme={null}
deepline session limit --dollars 10
```

Check your balance:

```bash theme={null}
deepline billing balance
```

Run the default sample (2-5 rows):

```bash theme={null}
deepline enrich --input leads.csv --output enriched.csv \
  --with '{"alias":"email","tool":"name_and_domain_to_email_waterfall","payload":{"first_name":"{{first_name}}","last_name":"{{last_name}}","domain":"{{domain}}"}}'
```

Look at the results. Check what you spent with `deepline session usage`.

If the sample looks good:

```bash theme={null}
deepline enrich --input leads.csv --output enriched.csv --all \
  --with '{"alias":"email","tool":"name_and_domain_to_email_waterfall","payload":{"first_name":"{{first_name}}","last_name":"{{last_name}}","domain":"{{domain}}"}}'
```

## Large lists (1000+ rows)

Start with 10 rows:

```bash theme={null}
deepline enrich --input leads.csv --output enriched.csv --rows 0:10 --with '...'
```

Check per-row cost. Multiply by total rows. Set your limit slightly above that, then run full.

## Monitoring

```bash theme={null}
# This session
deepline session usage

# Account balance
deepline billing balance

# Monthly limit state
deepline billing limit

# Recent calls
deepline billing usage --limit 50

# Export to CSV
deepline billing history --time 1m --output usage.csv
```

## FAQ

**How do I set a spending limit?**

`deepline session limit --dollars N` for per-session. `deepline billing --set-monthly-limit N` for monthly.

**What happens when I hit my limit?**

API calls stop. Session limits you can clear and continue. Monthly caps you wait until next cycle.

**Why is my estimate way higher than actual cost?**

Estimates are worst-case. They assume every provider charges you and every validation fails. Actual costs are lower because waterfalls stop when they find valid data.

**How do I check spending?**

`deepline session usage` for this session. `deepline billing balance` for account total.