> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deepface.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Spending alerts

> Configure budget, usage-spike and spending-cap emails through the dashboard, account API, repository CLI or MCP.

The dashboard, API, CLI and MCP use the same saved account settings.
Configure up to three budget alerts and three independent spike alerts, including
their enabled switches, amounts, lookbacks and percentages. `capEmailEnabled`
controls cap-hit emails; it does not change the spending cap itself.

## Settings

Settings amounts are **USD cents**. Snapshot totals are **micro-USD**
(1 USD = 1,000,000 micro-USD). Calendar boundaries use the returned billing
timezone. Charged usage and completed no-face results count toward spend;
failures, free calls and wallet top-ups are excluded.

```json theme={null}
{
  "thresholds": [
    { "id": "monthly-budget", "enabled": true, "amountCents": 5000, "period": "monthly" }
  ],
  "spikeAlerts": [
    { "id": "matching-weekday", "enabled": true, "mode": "same_weekday", "samples": 5, "percentAbove": 40, "minimumSpendCents": 100 },
    { "id": "weekly-spike", "enabled": true, "mode": "weeks", "samples": 4, "percentAbove": 50, "minimumSpendCents": 100 },
    { "id": "monthly-spike", "enabled": false, "mode": "months", "samples": 3, "percentAbove": 30, "minimumSpendCents": 100 }
  ],
  "capEmailEnabled": true
}
```

Budget periods are `daily` or `monthly`. Spike modes are `days`, `weekdays`,
`same_weekday`, `weeks` and `months`. Lookbacks use previous completed periods:
up to 90 days/weekdays, 52 matching weekdays/weeks, or 12 months. Weeks start
on Monday; months use calendar boundaries. Today, this week or this month is
compared with the corresponding completed-period average. Alerts wait for the
full lookback history. Weekday alerts are inactive on weekends.

Keep rule IDs stable when editing to preserve delivery history. IDs must be
unique within each list and contain 1–64 letters, digits, underscores or hyphens.
Budget and minimum-spend amounts are integer cents from 1 to 1,000,000,000.
`percentAbove` accepts numbers from 0 to 10,000. The minimum-spend amount prevents
small spikes from triggering an email.

Checks run every five minutes, with at most one accepted notice per rule/period.
Disabling or removing a rule cancels only its unattempted notices. Saving
settings does not send a test email.

## Account API

Use **`https://www.deepface.dev`**, rather than the compute gateway, with your
existing standard API key or MCP key. Both `Authorization: Bearer` and
`X-API-Key` work. The key selects the account; there is no account parameter.
Revoked keys and inactive accounts cannot access settings.

```bash theme={null}
curl --fail-with-body https://www.deepface.dev/api/billing/spending-alerts \
  -H "Authorization: Bearer $DEEPFACE_API_KEY"

# Save the settings example above as settings.json first.
curl --fail-with-body -X PATCH https://www.deepface.dev/api/billing/spending-alerts \
  -H "Authorization: Bearer $DEEPFACE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @settings.json
```

`GET` and successful `PATCH` return a snapshot containing `settings`, usage
totals, the billing timezone and per-rule `spikeEvaluations` with baseline
readiness. `PATCH` replaces the **complete settings document**: read first,
edit the `settings` object, then submit it. Do not submit the entire snapshot.
Empty arrays remove all rules of that type. Invalid settings return HTTP 400
without writing. Invalid explicit credentials return HTTP 401 even if a browser
session is present. Responses are private and are not cached.

## Repository CLI

Use Node.js 24 in a deepface.dev repository checkout; no extra package or global
installation is required. Set `DEEPFACE_API_KEY` through your shell's secret
manager or environment. Keys are not accepted as command arguments.

```bash theme={null}
npm run --silent cli -- spending-alerts get
npm run --silent cli -- spending-alerts set --file settings.json
npm run --silent cli -- spending-alerts set --file - < settings.json
```

Commands return JSON and a nonzero exit status on failure.
`DEEPFACE_BASE_URL` optionally selects another deployment. HTTPS is required
except for HTTP loopback during local development. Redirects are rejected.

## MCP

Connect to `https://www.deepface.dev/mcp` with ChatGPT OAuth or a dedicated MCP key.

| Tool | Arguments | Result |
| - | - | - |
| `get_spending_alerts` | `{}` | Current settings, usage and baseline readiness |
| `update_spending_alerts` | `{ "settings": { ... } }` | Snapshot after replacing the full settings document |

The `settings` argument uses the JSON shape above. Tools configure only the
connected account. They cannot change the recipient, tariffs, spending cap or
another account's settings. Refresh the client's tool list after upgrading
an existing connection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.