Monitor usage and provider keys

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

1. 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.
2. 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

1. 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 and /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.