status

At-a-glance budget usage and provider health for a Solwyn project, optionally with the spend forecast and top failover groups

status reads a project's budget summary and provider health — spend against limit, and per-provider circuit state, success rate, latency, errors, and failovers over a fixed 24-hour window. It never reserves or authorizes spend; it is a pure read.

Terminal

solwyn --project <project_id> status [--forecast] [--failovers]

Option	Type	Default	Purpose
`--forecast`	boolean	`false`	Append the month-to-date spend forecast.
`--failovers`	boolean	`false`	Append the top failover groups for the last seven days.

Resolve the project with --project, the SOLWYN_PROJECT_ID environment variable, or a default_project in your config file — in that order. A missing project exits 2 before any credential is resolved.

Contract
Auth	any (project key or JWT)
Exit codes	`0` success · `1` generic/API · `2` usage · `3` auth · `5` not found
JSON schema	`solwyn.status.v1`

Output

The human table lists the budget summary, then a block of rows per provider:

Terminal

$ solwyn --project proj_0123456789abcdef01234567 status
Field                                     Value
Project                             proj_0123456789abcdef01234567
Budget limit                               100.00
Current usage                               37.50
Remaining budget                            62.50
Budget period                   monthly (2026-07)
Budget mode                             hard_deny
Utilization                                37.50%
Provider health window                24h (fixed)
openai circuit                             closed
openai circuit source                    reported
openai success                  98 / 100 (98.00%)
openai latency                          245.50 ms
openai errors / failovers                   2 / 1
openai model failovers                          1
openai provider failovers                       0
anthropic circuit                            open
anthropic circuit source                 inferred
anthropic success                40 / 50 (80.00%)
anthropic latency                       410.00 ms
anthropic errors / failovers               10 / 3
anthropic model failovers                       1
anthropic provider failovers                    2

Field	Meaning
Budget limit / Current usage / Remaining budget	Spend against the cap for the current period, in USD
Budget period	`daily`, `weekly`, or `monthly`, with the period key
Budget mode	`alert_only` or `hard_deny`
Utilization	Spend as a percentage of the limit
Savings	Under a user login only: the cost `hard_deny` blocked, its upper bound when known, and the blocked-call count. `—` when none.
Provider health window	Always the last 24 hours.
`<provider>` circuit	Failover circuit state — `closed` = healthy, `open` = down, `half_open` = recovering, `unknown` = insufficient data
`<provider>` circuit source	`reported` when an SDK instance reported its breaker state, `inferred` when Solwyn derived it from call outcomes
`<provider>` success	Successful calls over total, with success rate
`<provider>` latency	Average end-to-end latency in milliseconds
`<provider>` errors / failovers	Error count and total times traffic moved to a fallback
`<provider>` model failovers / provider failovers	The failover total split by whether a different model or a different provider served the call

Only quantities and structural labels are read — counts, rates, durations, and circuit states — never prompt or response content. See Privacy for the full boundary.

Under a user login, status makes one extra account read to attach savings, so a JWT run makes three requests where a project-key run makes two. With --failovers, stderr notes Showing top 50 groups of an unknown total.

With `--forecast` and `--failovers`

The extra rows are appended after the provider block:

Forecast EOM                                                   $75.000000
Forecast burn rate                                        $2.500000 / day
Forecast 95% CI                                   $60.000000 - $90.000000
Forecast insufficient data                                             no
Failover range                                                         7d
Failover 1 route                openai/gpt-5 -> anthropic/claude-sonnet-4
Failover 1 reason                                            Circuit open
Failover 1 error class                                                  -
Failover 1 events                                                       4
Failover 1 cost                                                 $1.234567
Failover 1 first/last         2026-09-01T10:00:00Z / 2026-09-05T12:30:00Z

forecast and providers failovers give each of these its own command and options.

JSON output

Terminal

$ solwyn --project proj_0123456789abcdef01234567 --json status
{
  "schema": "solwyn.status.v1",
  "project_id": "proj_0123456789abcdef01234567",
  "budget": {
    "budget_limit": 100.0,
    "current_usage": 37.5,
    "remaining_budget": 62.5,
    "budget_period": "monthly",
    "budget_mode": "hard_deny",
    "period_date": "2026-07",
    "utilization_pct": 37.5
  },
  "providers": [
    {
      "provider": "openai",
      "total_calls": 100,
      "success_count": 98,
      "error_count": 2,
      "failover_count": 1,
      "model_failover_count": 1,
      "provider_failover_count": 0,
      "success_rate": 98.0,
      "avg_latency_ms": 245.5,
      "circuit_state": "closed",
      "circuit_source": "reported"
    }
  ]
}

Pretty-printed here; the CLI emits the envelope as a single line. Three optional keys — forecast, failovers, and savings — appear only when requested or applicable; they are omitted, not emitted as null. See Scripting for the envelope and exit-code contract.

budget status — budget state alone, with an optional CI utilization gate
overview — the account-wide calendar-month view
costs — aggregate cost breakdown by model, provider, or day
Provider failover — how the SDK routes around a failing provider

Output

With --forecast and --failovers

JSON output

Related

On this page

With `--forecast` and `--failovers`