How to monitor any API's credit balance and get alerted when it drains fast

Which endpoints qualify for balance monitoring

To monitor a provider that lacks a native integration, the provider must offer an official endpoint that exposes current balances or cumulative spend. Costbrake uses this data through its Custom API connection type.

Not every billing API works. To work with Custom API monitoring, the endpoint must meet four requirements:

• HTTPS GET requests only. The endpoint must return data in response to a standard HTTPS GET request. It cannot require a POST, PUT, or custom body payload.
• Valid JSON responses. The endpoint must respond with a JSON object or array, served with a JSON content type. Raw text, HTML, or CSV exports will fail.
• Fast and compact. The server must answer within 10 seconds, and the payload size must not exceed 256 KB.
• US dollars or a fixed unit. The number must be in US dollars or in a unit with a fixed rate to the dollar, such as cents or credits at a set price. An endpoint that reports in euros or another currency won't work, because Costbrake would book the number as dollars.

The endpoint must also sit on a standard HTTPS port and use a proper host name rather than an IP address or internal name like .local or .internal. Costbrake does not follow HTTP redirects, so you need to provide the final destination URL directly.

The six Custom API fields

When you add a Custom API connection in Costbrake, either manually at https://app.costbrake.com/signin or via agent setup, you configure six fields:

1. Endpoint URL: The full HTTPS address of the balance endpoint. This is required and stored encrypted with AES-256-GCM.
2. Header name: The authentication header expected by the provider. It is optional and defaults to Authorization.
3. Header value: Your API credential formatted as the provider requires, such as Bearer your-key-here or a Basic auth string.
4. JSON path to the number: The path to the balance or spend property in the JSON payload, such as balance or data.account.credits. Costbrake supports dot notation, array indexing like items[0].amount, and an optional leading $, up to 16 steps deep.
5. The number is: balance when the number goes down as you spend (prepaid credit), or spent when it is a running total that goes up. The default is balance.
6. Units per US dollar: The multiplier required to convert the reported number into US dollars. It defaults to 1. If the API reports in cents, you enter 100. If it reports in smaller fixed increments, enter the exact count of units that equals $1.00.

How spend is derived between checks

Costbrake does not evaluate your raw credit balance against a floor; instead, it derives spend by measuring the difference between checks.

When you configure an endpoint as a balance, spend is the drop in funds between two successful polls. If your balance reads $100 on check A and $92 on check B, Costbrake records $8 of spend. When you set the type to spent, spend is the rise between check A and check B.

The first check sets the baseline level, meaning spend only begins recording from the second check onward. If you top up your account or receive a credit refund, the balance goes up. When Costbrake detects a higher balance on a balance connection (or a lower reading on a spent connection), it books $0 of spend and resets the baseline to that new level. Spend occurring in the exact same check window as a balance top-up is not recorded.

Spend between two checks is distributed evenly across the hours between them. If checks occur more than 2 hours apart, Costbrake flags the resulting figures as estimates. If polling stops or fails for more than 7 days, the tracker resets its baseline entirely.

Three balance endpoints that fit

Plenty of APIs without a Costbrake integration publish a balance endpoint that fits. Here are three, straight from their API docs. Test yours with curl first, sending only the one auth header, because that is exactly the request Costbrake makes:

curl -sf -H "Authorization: Bearer $NOVITA_API_KEY" \
  https://api.novita.ai/openapi/v1/billing/balance/detail | jq '.availableBalance'

Novita AI

Novita AI exposes balance data through an HTTPS GET to https://api.novita.ai/openapi/v1/billing/balance/detail, with your key in the Authorization header as Bearer followed by the key.

The response contains string-encoded amounts in units of 1/10000 USD, where 10000 equals $1.00:

• availableBalance: your credit balance
• cashBalance: remaining balance from top-ups
• creditLimit: maximum amount you can owe
• pendingCharges: defaults to 0
• outstandingInvoices: amount currently owed

To track your available credits, point the JSON path to availableBalance and set Units per US dollar to 10000.

Bright Data

Bright Data provides an account balance endpoint via an HTTPS GET request to https://api.brightdata.com/customer/balance. API keys can be obtained from account settings at https://brightdata.com/cp/setting/users and must be passed as a Bearer token in the Authorization header.

The endpoint returns HTTP 200 with application/json containing four numerical properties in USD:

• balance: current available funds
• credit: account credit
• prepayment: monthly prepayment commitment on custom plans
• pending_costs: expected usage charges for next month's invoice

Note that Bright Data has no Account Management API endpoint for free-tier allowances, credits used, credits remaining, renewal dates, or whether auto-recharge is enabled. To monitor available funds, track balance with Units per US dollar set to 1. If you want to track upcoming invoice costs instead, point to pending_costs and set "The number is" to spent.

Plivo

Plivo serves its API over HTTPS at https://api.plivo.com/v1/ and requires Basic authentication using your AUTH ID and AUTH TOKEN. You can retrieve your account object with an HTTPS GET request to https://api.plivo.com/v1/Account/{auth_id}/ with no arguments.

The returned JSON includes:

• cash_credits: account credits in USD as a string (such as "1.80900")
• account_type: standard or developer
• auto_recharge: boolean for auto-recharge threshold status
• billing_mode: prepaid or postpaid
• api_id: unique request identifier

Plivo uses Basic auth, and Costbrake won't take credentials in the URL, so put them in the header instead: header name Authorization, header value Basic followed by the base64 of AUTH_ID:AUTH_TOKEN (printf '%s' "$PLIVO_AUTH_ID:$PLIVO_AUTH_TOKEN" | base64). Then point the JSON path to cash_credits with Units per US dollar set to 1, and keep the trailing slash in the URL, since Costbrake doesn't follow redirects.

Alerting rules, limits, and brakes

Because Custom API connections translate balance changes into spend, they inherit Costbrake's standard alerting rules:

• Spike alerts: Triggers when an hour costs at least $5 more than usual and exceeds 3x your rolling 7-day hourly average.
• Budget alerts: Fires when total spend reaches 50%, 80%, and 100% of your configured target.
• Forecast alerts: Flags when your month-to-date spend combined with your last 72 hours of burn puts you on track to cross your budget before month-end.

Costbrake has no low-balance alert. If you want a warning when your credit drops below $20, a Custom API connection won't fire on that number; it alerts on spend. The workaround is a budget: set a monthly budget the size of what you usually top up, and the 80% alert tells you most of it is gone. On Pro and Team you can scope that budget to this one connection; the Free plan only allows org-wide budgets.

Custom API connections have no brakes. Costbrake can only brake providers it has a full integration for (18 of them, and only when an admin clicks and confirms), so for a Custom API you get alerts and then act in the provider's own dashboard.

For wider monitoring across native integrations, Costbrake supports 23 providers directly, including AWS, Google Cloud, Azure, Cloudflare, GitHub, Vercel, OpenAI, Anthropic, OpenRouter, xAI, DeepSeek, Moonshot AI, DataForSEO, Apify, Vast.ai, RunPod, Railway, Neon, Supabase, Turso, fal.ai, Twilio, and ElevenLabs. If you use those services, see our guides on AI API spend monitoring and tracking DeepSeek API balances.

To manage your plans and notification routes, Costbrake delivers email alerts on the Free plan ($0 with 2 connections), adding Slack, Discord, and signed webhooks on the Pro plan ($12 a month with 10 connections), and PagerDuty with REST API access on the Team plan ($39 a month with 50 connections). Each Custom API connection counts toward those connection limits. Review full plan breakdowns on the Costbrake pricing page or learn how to send cloud billing alerts to Slack or Discord.

Fixing common connection errors

When testing or saving your Custom API connection, Costbrake validates the response. If your configuration fails, the dashboard surfaces one of several explicit error states:

• HTTP 401: unexpected response. The provider rejected your credentials. Verify your header name and format. In Plivo, a 401 indicates an invalid Auth ID or Auth Token.
• HTTP 404: unexpected response. The URL is misspelled or the resource does not exist on that host.
• HTTP 301: unexpected response. Redirects are not followed, so use the final URL. Update your URL field to point directly to the target location.
• HTTP 200: unexpected response. The server returned an OK status, but the payload was not valid JSON.
• HTTP 200: unexpected response (no usable amount at data.balance). The JSON path did not resolve to a number or a numeric string. Ensure the path does not point to an object, null, or empty string.
• The endpoint did not answer within 10 s. The provider's billing server timed out.
• Unexpected response: larger than 256 KB. The endpoint returned more data than the supported payload cap.
• Use a host name, not an IP address. Raw IP addresses are rejected.
• The endpoint must use the standard HTTPS port. Custom ports outside port 443 are not allowed.
• Costbrake can't send a Cookie header. Session cookies can't be used to sign in. Costbrake also won't send Host, Forwarded, X-Forwarded-*, CF-* or Proxy-* headers, so use the provider's API key header.
• HTTP 429: unexpected response. The provider rate-limited the request. Costbrake sends one GET per check, so look for other traffic using the same key.