Guide · OpenAI

How to get alerted before a surprise OpenAI API bill

The fastest way to limit a surprise OpenAI bill is to find out the same day spend jumps, not when the invoice arrives. Here is how to get an alert in Slack or Discord when OpenAI costs spike, in about five minutes, for free.

Why the built-in limits aren't enough

OpenAI's dashboard lets you set project budgets and email notification thresholds. These are monthly numbers: they tell you when you cross a total, not when one day suddenly costs ten times the usual. A retry loop or a leaked key can burn a lot of money before a monthly threshold notices.

What you want is an anomaly alert: "today is 3× your normal day." That catches problems while they are still cheap. Keep the provider's hard limit as a backstop.

1. Create a key that can read costs

Create an admin key in the OpenAI dashboard under Organization settings → Admin keys. Only organization owners can create one. A regular project API key cannot read cost data and returns 401.

2. Add billshock to a repo

npx billshock init

This writes billshock.yml and .github/workflows/billshock.yml, which runs every hour. Trim the config to what you need:

providers:
  openai:
    apiKey: ${OPENAI_ADMIN_KEY}
    rules:
      dailyCap: 25        # USD per UTC day
rules:
  spikeMultiplier: 3      # 3x the 7-day average
  spikeMinAmount: 5
notify:
  slackWebhook: ${SLACK_WEBHOOK_URL}

3. Add secrets and run it once

In your repo, go to Settings → Secrets and variables → Actions and add OPENAI_ADMIN_KEY plus a Slack or Discord webhook URL. Then open the Actions tab and run the billshock workflow manually. The run summary shows today, yesterday, the 7-day average, month-to-date and the projected month total.

When something looks wrong, you get one message per anomaly:

ALERT openai: $41.20 spent on 2025-10-07, 8.3x the 7-day average of $4.95

No webhook? A run with a new alert fails, and GitHub emails you about the failed workflow.

How it works

billshock reads GET /v1/organization/costs with daily buckets across all projects. Each run compares yesterday and today-so-far against the trailing average and your caps. Sent alerts are remembered in the Actions cache so you're not pinged every hour. Your key stays in your repo's secrets and is only sent to OpenAI's API.

FAQ