FeaturesProjects API

Budgets

Set a per-project spending limit, enforced hard or alerted soft

A project’s budget_config caps its spend over a rolling period. hard_limit rejects the project’s requests with 402 once the limit is reached; soft_limit only fires alerts. Set it on create or PATCH; set it to null to remove the limit.

Fields

FieldDescriptionType
amountBudget amount in USD, greater than 0number
perioddaily, weekly, monthly, quarterly, or yearlyenum
enforcement_modehard_limit (requests rejected with 402 at the limit) or soft_limit (alerts only)enum
alert_thresholdsPercentages that trigger alerts, e.g. [80, 90]list of integers, 1-100

Set a budget

$curl -X PATCH https://api-gateway.merge.dev/v1/projects/{project_id} \
>  -H "Authorization: Bearer mgmt_<your_management_key>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "budget_config": {
>      "amount": 100,
>      "period": "monthly",
>      "enforcement_mode": "hard_limit",
>      "alert_thresholds": [80, 90]
>    }
>  }'

Requests over a hard limit fail with 402 and a project_budget_exceeded error before any provider call, and responses include X-Project-Budget-Remaining-USD and X-Project-Budget-Limit-USD headers as the limit approaches. Budget changes can take up to an hour to take effect in enforcement.