# Monitor Ravn Usage and Credit Spend — Ravn

Canonical: https://askravn.com/skills/monitor-usage-and-credits

Claude skill

# Monitor usage and provider keys

Keep any Ravn job inside its lookup budget. Check the balance before starting, estimate the lookups, watch usage while it runs and stop cleanly when limits are hit. The account tools are free, so there is no reason not to check.
[Download SKILL.md](https://askravn.com/skills/monitor-usage-and-credits/SKILL.md) [Start free](https://askravn.com/#start)

Install
## One command.
Installs into `~/.claude/skills` for Claude Code. In Claude, upload the downloaded file under Settings → Capabilities → Skills.
```
npx ravn skill install monitor-usage-and-credits
```

## When to use

- Before any job that uses the provider tools (people, companies, carrier checks).
- When an agent runs Ravn on a schedule or in a loop and needs a hard lookup cap.
- "How many lookups do I have left?", "What did we use this week?", "Why did my run stop?"

## Before you start

- There is one meter: lookups. Every tool is one lookup and a miss is free. Free plan: 1,000 lookups in total. Ravn: $24/month includes 10,000 lookups a month, then $1 per 1,000 ($0.001 each), billed monthly, up to a monthly spending cap (default $100 beyond the plan; `ravn cap <dollars>`, 0 stops at 10,000). At the cap the API returns 429 `spend_cap_reached`: stop and tell the human.
- The people, company and carrier tools run on your own provider account (People Data Labs for people and company, Twilio for carrier). With no key connected the tool returns 403 `provider_key_required`; add one with `ravn keys add pdl` (or `twilio`). Ravn's own checks (verify email, find email, scrape website, validate phone, IP to company) need no key.

## Steps

- Check the account. Free.

```
{}
```

Call `get_account` (or run `npx ravn whoami`). Read `plan`, `fair_use.lookups_remaining_5h` and `fair_use.lookups_reset_5h`. 2. Check prices for the tools you plan to use. Call `get_billing` with `{}` (or `npx ravn billing`). The `costs` map shows each tool as one lookup or free, flags which tools need a provider key, and shows the renewal date. 3. Estimate the job: one lookup per row. For CSVs, `npx ravn enrich <file> --tool <tool> ... --dry-run` prints the row count, lookups per row and what you have left, and calls nothing. 4. Set a cap with the human before starting, in lookups. Default: ask before anything over 100 lookups. 5. During the run, read `metadata` on every response: `lookups_used` and `fair_use.lookups_remaining_5h`. Keep a running total. Stop when the total reaches the cap. 6. Branch on errors:    - 429 `fair_use_exhausted` or `rate_limited` (exit code 4): wait for the `Retry-After` header or `lookups_reset_5h`. The CLI `enrich` command waits by itself unless `--no-wait` is set, and resumes from saved progress.    - 403 `provider_key_required`: the tool needs a provider key this account has not connected. Stop and tell the human to add one with `ravn keys add pdl` (or `twilio`). 7. After the run, check spend with `get_usage`:

```
{ "days": 7 }
```

It returns lookups per 5-hour window, per day and by reason, for up to 90 days.

## Output

A short budget report:

- Plan, lookups used this month, the spending cap and when the period renews.
- Estimated lookups before the job and actual lookups after it.
- Lookups used in the period from `get_usage`.
- Any stop: the error code, rows completed, rows `dropped`, and what is needed to finish.

## Rules

- Never upgrade the plan or add a provider key on the human's behalf. Give them the link and the number.
- Never retry a 429 in a loop. Stop, report and wait.
- Do not split a job across many small calls to get around a cap the human set.
- Keep the API key out of logs, chat and files you share.
- These checks are for budgets. Data rules still apply to the job itself: no FCRA uses, never contact opted-out people. See [/privacy#optout](https://askravn.com/privacy#optout) and [/fair-use](https://askravn.com/fair-use).

## Example prompt

You're going to run Ravn every night on new leads. Keep it under 300 lookups a night, tell me if we're running low, and don't change the plan without asking.

## More [skills](https://askravn.com/skills)
Install them all with `npx ravn skill install --all`.
- [Ravn Core Skill for ClaudeUse Ravn from Claude or the terminal to validate emails, find work emails, enrich CSVs, and look up companies, phones and people..](https://askravn.com/skills/ravn)
- [Reduce Email Bounce Rate on a Stale ListUse when bounces are hurting deliverability and someone wants a stale list re-verified, segmented by risk score and given a clear re-send policy..](https://askravn.com/skills/reduce-bounce-rate)
- [Sales Territory Planning by State and IndustryUse when a sales leader wants a territory mapped, listing companies by state, industry and size and then the decision makers at the best-fit accounts..](https://askravn.com/skills/territory-planning)
- [Verify an Email List Before a CampaignUse when someone wants to verify and clean an email list before a campaign, dropping invalid and risky addresses so only send-ready contacts remain..](https://askravn.com/skills/verify-email-list)
- [Company Account Research BriefUse when someone wants a one-page research brief on a company covering what it does, size, location, tech, public contacts and key people, from its domain..](https://askravn.com/skills/account-research-brief)
- [Build a Prospect List from Your ICPUse when someone describes their ideal customer and wants a prospect list built from scratch, with people found by title and company and emails verified..](https://askravn.com/skills/build-prospect-list)