Skip to content

Feature: Account-level weekly cost limit (weekly_cost_limit) for Anthropic accounts #704

@xsha511

Description

@xsha511

Background

Claude Max subscriptions have two rate-limit windows:

  • 5-hour window — short-term usage cap
  • 7-day window — weekly usage cap

Sub2API currently supports proactive cost control only for the 5h window via window_cost_limit in the account's extra field. For the 7d window, Sub2API can only reactively handle 429 responses by parsing anthropic-ratelimit-unified-7d-utilization and anthropic-ratelimit-unified-7d-reset headers.

Problem

There is no way to proactively set a weekly cost limit per account. Administrators cannot configure "stop scheduling this account after it spends $X this week." The only option is to wait until Anthropic returns a 429 with 7d window exhaustion, which means:

  1. The account has already hit its hard limit — no budget headroom control
  2. No ability to set a conservative weekly budget below Anthropic's hard cap
  3. Cannot distribute weekly quota evenly across accounts (some accounts may burn through their weekly allowance early in the week)

Adjusting window_cost_limit to indirectly control weekly spend is imprecise (168h / 5h = ~33 windows, hard to predict actual usage distribution).

Proposed Solution

Add a weekly_cost_limit field to the account extra configuration, similar to how window_cost_limit works:

{
  "window_cost_limit": 50,
  "window_cost_sticky_reserve": 10,
  "weekly_cost_limit": 200,
  "weekly_cost_sticky_reserve": 20
}

Scheduling behavior (same three-state pattern as window cost):

Current weekly cost State Behavior
< weekly_cost_limit Schedulable Accept new requests normally
weekly_cost_limit ~ weekly_cost_limit + sticky_reserve StickyOnly Only allow existing sticky sessions
>= weekly_cost_limit + sticky_reserve NotSchedulable Fully stop scheduling

Implementation considerations:

  • Weekly window start could align with Anthropic's 7d window (rolling 7 days) or use a fixed weekly reset (e.g., Monday 00:00 UTC)
  • Cost calculation should reuse the existing usageLogRepo.GetAccountWindowStats() pattern with a 7-day lookback
  • Can be integrated into the existing isAccountSchedulableForWindowCost() filter chain in GatewayService

Use Case

Operators managing multiple Claude Max subscription accounts who want to:

  • Set conservative weekly budgets below Anthropic's hard limit
  • Evenly distribute usage across accounts throughout the week
  • Prevent any single account from consuming its entire weekly quota early

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions