---
title: "Read the caller's current API request budget window."
method: GET
path: "/api/v1/budget"
tags: ["Agents"]
---

# Read the caller's current API request budget window.

`GET /api/v1/budget`

## Request

- Base URL: `https://huggingbay.xyz`
- URL: `https://huggingbay.xyz/api/v1/budget`
- Auth: none required

Returns limit, remaining, windowSeconds and resetSeconds for this server instance. Anonymous callers see the client IP bucket; authenticated callers see the token bucket when per-token budgets are active (as reported by this response). The request does not consume a budget unit.

**Inputs.** No path or query fields are required. No request body is required.

**Outputs.** See each status below for its media type, schema and headers. A missing record or unavailable capability is not a successful empty result.

**Errors.** API JSON failures use the documented response schema. Read code, message and next; retry only when the response allows it. Auth, invalid input and missing records need a caller change.

**Rate limits.** Public read budgets apply by client IP and route group. This operation can have a smaller route-specific budget. Read Retry-After on 429 or retryable 503 responses.

## Response `200`

Current budget window

- object
  - `schemaVersion` 'hugging-bay.api-budget.v1', required
  - `identity` object, required
    - `kind` 'ip' | 'token', required
    - `id` string, nullable
  - `budget` object, required
    - `scope` string, required
    - `limit` integer, required
    - `used` integer, required
    - `remaining` integer, required
    - `windowSeconds` integer, required
    - `resetSeconds` integer, required
    - `keyed` boolean, required
  - `flags` object
    - `perTokenApiBudget` boolean
    - `bearerPresent` boolean

## Other responses

- `401`: Bearer token present but not valid.

## Changes

- **2026-10-26** `554a75e31930`: 1 warning
  - added the new `not-served` enum value to the `status/anyOf[subschema #2]/` response property for the response status `401`
- **2026-10-23** `b91e61a85ee0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/huggingbay/apis/hugging-bay-public-api/changes/api/v1/budget/get.md)

---

[API](https://skmtc.dev/huggingbay/apis/hugging-bay-public-api.md) - [All operations](https://skmtc.dev/huggingbay/apis/hugging-bay-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/huggingbay/apis/hugging-bay-public-api/revisions/c5016474b723?raw)