Documentation
¶
Overview ¶
Package fetcher talks to the (unofficial) claude.ai Usage endpoint.
This is the ONE file that needs patching when Anthropic changes the endpoint shape. Keep it small and self-contained.
Endpoint captured 2026-05-13 from claude.ai/settings/usage:
GET https://claude.ai/api/organizations/<org_uuid>/usage
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrNoCredential = errors.New("no session cookie; run `claude-usage login`") ErrAuthExpired = errors.New("session expired; run `claude-usage login` again") ErrRateLimited = errors.New("claude.ai rate-limited the request; try again in a minute") )
Sentinel errors that callers (CLI / tray) can branch on.
Functions ¶
This section is empty.
Types ¶
type Bucket ¶
type Bucket struct {
PercentUsed float64 `json:"utilization"`
ResetsAt time.Time `json:"resets_at"`
}
Bucket is one row on the Usage page.
type Client ¶
type Client struct {
HTTP *http.Client
SessionCookie string // value of `sessionKey` cookie on claude.ai
OrgID string // organization UUID; required by the endpoint
UserAgent string
// Mock makes Fetch return data from samples/usage-response.json instead
// of hitting the network. Useful before Phase 0 is complete.
Mock bool
// MockPath overrides where mock data is read from. Defaults to
// "samples/usage-response.json" relative to the working directory.
MockPath string
}
Client fetches Usage snapshots.
type NamedBucket ¶
NamedBucket pairs a Bucket with its display label.
type Usage ¶
type Usage struct {
Session Bucket `json:"five_hour"`
Weekly Bucket `json:"seven_day"`
Sonnet Bucket `json:"seven_day_sonnet"`
Design Bucket `json:"seven_day_omelette"`
// FetchedAt is set by the fetcher; not part of the upstream payload.
FetchedAt time.Time `json:"-"`
}
Usage is the normalized snapshot returned by Fetch.
Fields map to claude.ai /api/organizations/<id>/usage payload (captured 2026-05-13). Bucket objects in that payload can be either {utilization, resets_at} or JSON null; both decode to a zero-valued Bucket here, which renderers treat as 0% / "no reset known".
func (Usage) Buckets ¶
func (u Usage) Buckets() []NamedBucket
Buckets returns the four buckets in display order. Stable for iteration.
Source Files