feat: expose balance / token-usage to the API (or at least via a UI toggle)

[sophronesis]

Problem

There's currently no way to programmatically read an account's credit balance or token usage from Skyvern Cloud. The information exists - I can see it in the dashboard at https://app.skyvern.com/billing - but it's not reachable from a script with my API key.

This matters when you're running large batches and want to:

• detect "running low on balance" before the next batch dispatches and silently fails
• track per-run cost so internal dashboards can show "this county costs us $X" over time
• alert when daily usage spikes past a threshold

Right now the workaround is: a human opens the web dashboard. For an automation product, that's a rough corner.

Current state (as far as I can tell from the public repo)

The endpoints exist server-side:

# fern/openapi/overrides.yml
/api/v1/billing/checkout:    { x-fern-ignore: true }
/api/v1/billing/portal:      { x-fern-ignore: true }
/api/v1/billing/state:       { x-fern-ignore: true }
/api/v1/billing/change-tier: { x-fern-ignore: true }

x-fern-ignore: true removes them from the generated public SDK, and the FAQ (docs/developers/debugging/faq.mdx) just points users to the dashboard. The recent persistence work in #5656 also notes "public API unchanged - placeholder preserved", which suggests this is a deliberate hold rather than a missing implementation.

Asks (in order of preference)

1. Public read-only endpoint for balance + recent usage. e.g.

   GET /v1/billing/state
   → { current_balance_usd, billing_tier, period_start, period_usage_usd, ... }
   
   GET /v1/billing/usage?from=...&to=...
   → { runs: [{ run_id, started_at, total_cost_usd, llm_tokens_in, llm_tokens_out }, ...] }
   

   Existing API key, read-only - no checkout/portal/tier-change exposure.

2. Or: a UI toggle / API-key permission to "allow programmatic billing reads". Off by default, opt-in per org. That way you don't have to expose it to every account, but power users who want it can flip it on.

3. Or even just: surface total_cost_usd (and ideally llm_tokens_in/out) on the existing GET /v1/runs/{run_id} response. That would at least let us roll up per-run cost client-side without a separate endpoint. Per-run cost is already persisted to the DB per feat: persist real LLM cost to DB + block-level attribution (public API unchanged — placeholder preserved) #5656.

Any of the three would unblock the use case. (3) feels lowest-risk because it's additive on an existing response shape.

Why not just scrape the dashboard?

It's an automation product specifically designed to avoid needing humans (or scripts) to drive a web UI for read access. Asking customers to write a Skyvern workflow that scrapes Skyvern's own dashboard to read their balance feels like exactly the loop you'd want to short-circuit.

Happy to help test any of these or open a PR for (3) if there's interest.

[bosslesss]

Thanks for opening this. I work on Inference Labs, and we see this failure mode often in multi-provider LLM stacks.

A practical pattern is:

1. Separate routing policy from provider SDK code.
2. Add retry budget + fallback chain to cap spend when upstream fails.
3. Track token usage and route low-risk traffic to cheaper tiers.

If useful, here are two free resources (no signup required for the content):

• Cost leak scanner: https://inference-labs.com/cost-leak-scanner.html?utm_source=github_issue&utm_medium=manual_comment&utm_campaign=issue_help_live&ref=Skyvern-AI/skyvern
• Routing templates: https://inference-labs.com/templates/?utm_source=github_issue&utm_medium=manual_comment&utm_campaign=issue_help_live&ref=Skyvern-AI/skyvern

If you share your constraints (max latency, max cost/request, acceptable failure rate), I can suggest a concrete policy shape directly in-thread.

[sophronesis]

@bosslesss I need to pay more just to see my spending via API? This sounds absurd.
If I really needed this feature - I would've parse Skyvern with local copy of itself. But is think this approach is so dirty. It should be part of data served via API, like other providers do.

[suchintan]

@sophronesis sorry for that other resposne - Bossless isn't affiliated with our projct

We will take a look at this. Thank you for this idea!

[sophronesis]

@suchintan it seems like already implemented feature, just it was removed upstream for some reason. would be nice to see it like you can with openai API