How to get your Tavily API usage, balance and spend programmatically

What the Tavily API exposes

Call it yourself

Credential. A normal Tavily API key (tvly-…).

curl https://api.tavily.com/usage \
  -H "Authorization: Bearer $TAVILY_API_KEY"

{
  "key": { "usage": 1003 },
  "account": {
    "current_plan": "Researcher",
    "plan_usage": 1003,
    "plan_limit": 1000,
    "paygo_usage": 0
  }
}

Gotchas

• plan_usage can exceed plan_limit. paygo_usage above zero means you're in overage at $0.008 per credit, up to the pay-as-you-go cap you set.
• The only rate-limit header is retry-after, on a 429.

How Tavily charges

Monthly subscription credits plus pay-as-you-go at $0.008/credit (as overage or standalone). Free tier included.

Free allowance. 1,000 a month.

At zero. 429. Paid plans continue at $0.008/credit up to a configurable paygo cap, then stop.

• 1,000 requests per minute, per key. 100 RPM dev, 1,000 RPM production.

Or let Argus track it

Paste the key once. Argus keeps the ledger, and your coding agent reads it through the MCP server.

• Reads the Tavily balance every hour and keeps the series, so you get burn per day (top-ups never count as negative spend) and days until it hits zero.
• Tracks the plan: the allowance, what's used this period, the reset date, and when you cross into overage.
• With the SDK, itemizes each call by endpoint and prices it at Tavily's per-operation rates.
• Emails you on low balance, days to zero, a spend spike, or projected overage.
• Hands all of it to your coding agent over MCP, so it can ask what a run cost or how much runway is left without leaving the editor.

> what has tavily cost today, and how long until it runs out?

get_overview       → tavily: mtd spend, burn per day, days to zero
get_request_costs  { "provider": "tavily", "limit": 25 }
get_advisories     → credits_low, spend_spike, rate_limit_low …

Questions

Does Tavily have an API for its balance?

Yes. GET https://api.tavily.com/usage reports credits used against your plan limit, plus pay-as-you-go usage. It reports what you've used, not what's left: remaining is plan_limit minus plan_usage.

Can I get Tavily spend per day from the API?

Not as a series. Derive it from how much the balance drops each day, ignoring top-ups.

What happens when Tavily credits run out?

Requests fail with HTTP 429. Paid plans continue at $0.008/credit up to a configurable paygo cap, then stop.

What key does Argus need for Tavily?

A normal Tavily API key (tvly-…).

Related

ExaFirecrawlParallel