Skip to main content
Credit budgets let you set spending limits per dimension (e.g., per team, brand, or user) on a shared credit pool. When a budget is exhausted, Monk fires a credit.budget.exhausted webhook — your gateway decides whether to block.

​
How It Works

  1. Create budgets on a contract with a credit wallet
  2. Each budget tracks an event property key/value pair (e.g., business_unit=dove)
  3. Monk checks ClickHouse usage on every refresh cycle
  4. When consumption reaches the cap, a webhook fires
  5. Your API gateway blocks or alerts based on the webhook
Budgets are spending limits, not reservations. All dimensions share the same credit pool. If one dimension uses less than its cap, others can still consume from the shared pool.

​
API Endpoints

​
List Budgets

GET /api/v1/contracts/:contractId/budgets
Returns all configured budgets. Cheap — reads from database only. 
{
  "data": {
    "budgets": [
      {
        "index": 0,
        "label": "Dove",
        "eventPropertyKey": "business_unit",
        "eventPropertyValue": "dove",
        "meterId": null,
        "maxCredits": 10000,
        "maxCreditsCents": null,
        "isExhausted": false
      }
    ],
    "contractId": "contract-uuid",
    "walletMode": "credits"
  }
}

​
Get Budget Usage

GET /api/v1/contracts/:contractId/budgets/usage
Returns all budgets with real-time consumption. Queries ClickHouse — use sparingly. 
{
  "data": {
    "budgets": [
      {
        "index": 0,
        "label": "Dove",
        "eventPropertyKey": "business_unit",
        "eventPropertyValue": "dove",
        "consumedUnits": 3200,
        "consumedCents": 2400000,
        "percentConsumed": 0.32,
        "maxCredits": 10000,
        "isExhausted": false
      }
    ],
    "queriedAt": "2026-04-09T12:00:00.000Z"
  }
}

​
Create a Budget

POST /api/v1/contracts/:contractId/budgets
For credit-based wallets (wallet has credit units): 
{
  "label": "Dove",
  "eventPropertyKey": "business_unit",
  "eventPropertyValue": "dove",
  "maxCredits": 10000
}
For dollar-based wallets (wallet tracks dollars only): 
{
  "label": "Dove",
  "eventPropertyKey": "business_unit",
  "eventPropertyValue": "dove",
  "maxCreditsCents": 500000
}
The walletMode field in the GET response tells you which cap field to use: "credits" → use maxCredits, "dollars" → use maxCreditsCents.

​
Update a Budget

PATCH /api/v1/contracts/:contractId/budgets/:index
Partial update — only provided fields change. When the cap changes, the alert state resets so the budget can refire. 
{
  "maxCredits": 15000
}

​
Delete a Budget

DELETE /api/v1/contracts/:contractId/budgets/:index
Returns the removed budget.

​
Scopes

EndpointRequired Scope
GET (list & usage)contracts:read
POST, PATCH, DELETEcontracts:write

​
Webhook Event

When a budget is exhausted, Monk fires credit.budget.exhausted. See Webhook Events for the full payload.