Budget Enforcement API

What is Budget Enforcement?

Budget Enforcement lets you add a pre-build check to your CI/CD pipelines. Before a workflow runs expensive jobs, it calls the Build Quota API to verify you still have budget remaining. If usage has crossed your threshold, the API returns allowed: false and your workflow can exit early — preventing overage charges.

This works with all supported providers: GitHub Actions, Bitrise, CircleCI, and GitLab CI. The API reads cached usage snapshots collected by Build Quota's background sync, so it responds in milliseconds without hitting your CI provider.

Quick Start

1. 1.Create an API key in your Build Quota settings. Copy the key immediately — it's only shown once.
2. 2.Store the key as a secret in your CI provider (e.g. BUILDQUOTA_API_KEY in GitHub Actions secrets).
3. 3.Add a budget check step at the start of your workflow. See the CI integration examples below.

API Reference

Authentication

Pass your API key in the Authorization header:

Authorization: Bearer bq_your_api_key_here

Query Parameters

Response

A successful response returns the budget decision and current usage:

{
  "allowed": true,
  "usage": {
    "provider": "github",
    "used": 1450,
    "included": 3000,
    "percent": 48,
    "unit": "minutes"
  },
  "threshold": 90,
  "message": "Usage at 48% — 1550 minutes remaining"
}

When the threshold is exceeded:

{
  "allowed": false,
  "usage": {
    "provider": "github",
    "used": 2850,
    "included": 3000,
    "percent": 95,
    "unit": "minutes"
  },
  "threshold": 90,
  "message": "Usage at 95% exceeds 90% threshold — 150 minutes remaining",
  "docs_url": "https://www.buildquota.com/docs/budget-enforcement"
}

Error Codes

CI Integration Examples

GitHub Actions

Add this step before your build jobs. Store your API key as a repository secret named BUILDQUOTA_API_KEY.

jobs:
  budget-check:
    runs-on: ubuntu-latest
    steps:
      - name: Check CI budget
        run: |
          RESPONSE=$(curl -s -w "\n%{http_code}" \
            -H "Authorization: Bearer ${{ secrets.BUILDQUOTA_API_KEY }}" \
            "https://www.buildquota.com/api/v1/budget/check?provider=github&threshold=90")

          HTTP_CODE=$(echo "$RESPONSE" | tail -1)
          BODY=$(echo "$RESPONSE" | head -1)

          if [ "$HTTP_CODE" != "200" ]; then
            echo "Budget check failed (HTTP $HTTP_CODE)"
            exit 1
          fi

          ALLOWED=$(echo "$BODY" | jq -r '.allowed')
          MESSAGE=$(echo "$BODY" | jq -r '.message')
          echo "$MESSAGE"

          if [ "$ALLOWED" != "true" ]; then
            echo "::error::Budget exceeded — build blocked"
            exit 1
          fi

  build:
    needs: budget-check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # ... your build steps

Generic Shell (any CI)

Works with CircleCI, GitLab CI, Bitrise, Jenkins, or any CI that can run shell commands:

#!/bin/bash
set -euo pipefail

RESPONSE=$(curl -sf \
  -H "Authorization: Bearer $BUILDQUOTA_API_KEY" \
  "https://www.buildquota.com/api/v1/budget/check?threshold=90")

ALLOWED=$(echo "$RESPONSE" | jq -r '.allowed')

if [ "$ALLOWED" != "true" ]; then
  echo "Budget exceeded — blocking build"
  echo "$RESPONSE" | jq .
  exit 1
fi

echo "Budget OK — proceeding with build"

FAQ