diff --git a/docs/billing-limits.mdx b/docs/billing-limits.mdx new file mode 100644 index 0000000000..f9e879cb19 --- /dev/null +++ b/docs/billing-limits.mdx @@ -0,0 +1,65 @@ +--- +title: "Billing limits and alerts" +sidebarTitle: "Billing limits & alerts" +description: "Set a monthly compute spend cap for your organization and get email alerts before you reach it." +--- + +Billing limits let you cap your organization's monthly compute spend so a runaway task or unexpected traffic spike can't blow your budget. Billing alerts notify you by email as you approach thresholds you choose. + +Billing limits and alerts are available to all [Trigger.dev Cloud](https://trigger.dev) organizations. They don't apply to self-hosted instances. + +You can find the settings in the dashboard: open the **Organization** menu in the top left, then **Settings** → **Billing limits**. + +![Billing limits and alerts settings](./images/billing-alerts-ui.png) + +## Setting a billing limit + +Choose one of three options: + +- **Plan limit**: Use your plan's maximum as the spending cap. +- **Custom limit**: Set your own monthly spend threshold. +- **No limit**: No cap is enforced. This is the default. + +A billing limit applies to your whole organization and covers billable environments: `production`, `staging`, and `preview`. Your `dev` environment is not affected. + +Optionally, enable **Cancel in-progress runs when this limit is reached** to immediately cancel executing runs when the limit is hit, instead of letting them finish naturally. + +## Billing alerts + +Billing alerts are email notifications sent when your monthly spend crosses a threshold. You can add multiple thresholds: + +- **With a billing limit set**: thresholds are percentages of your limit (e.g. 50%, 80%). +- **Without a billing limit**: thresholds are dollar amounts. + +Alerts only notify you — they never pause environments or reject runs. Use them on their own for visibility, or alongside a limit to get advance warning before enforcement kicks in. + +## What happens when you reach your limit + +When your organization's spend reaches the billing limit, billable environments enter a **grace period**: + +1. Queues pause across `production`, `staging`, and `preview`. In-progress runs finish naturally (unless you enabled **Cancel in-progress runs**). +2. New runs can still be triggered and are queued, but they won't start executing. Queued runs incur no compute cost until they start. +3. You have **24 hours** to review and decide what to do. + +If you don't act before the grace period ends, queued runs are canceled and new triggers are rejected for the rest of the billing cycle. + + + Billing limits are **soft limits**, not instantaneous hard caps. Usage is evaluated on a short + delay, so spend can briefly exceed your limit before enforcement applies. See our + [terms](https://trigger.dev/terms) for refund policy details. + + +## Resuming after hitting a limit + +To resume execution, increase or remove the billing limit from the **Billing limits** page. You'll be asked what to do with the runs that queued up during the pause: + +- **Resume queued runs**: everything that built up during the pause runs in order. +- **Cancel queued runs**: the backlog is discarded and only new triggers run going forward. + +Execution resumes automatically once you've resolved the limit. Limits also reset at the start of each billing cycle. + +## Tracking spend against your limit + +On the **Usage** page (Organization menu → **Usage**), a **Billing limit** marker appears on the usage bar alongside your current spend and plan included usage, so you can see how close you are at a glance. + +For tips on lowering your spend in the first place, see [How to reduce your spend](/how-to-reduce-your-spend). diff --git a/docs/docs.json b/docs/docs.json index f373503049..2a672a41d9 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -255,7 +255,13 @@ }, { "group": "Using the Dashboard", - "pages": ["run-tests", "troubleshooting-alerts", "replaying", "bulk-actions"] + "pages": [ + "run-tests", + "troubleshooting-alerts", + "billing-limits", + "replaying", + "bulk-actions" + ] }, { "group": "Troubleshooting", diff --git a/docs/how-to-reduce-your-spend.mdx b/docs/how-to-reduce-your-spend.mdx index 13ec16821b..7376ffafe7 100644 --- a/docs/how-to-reduce-your-spend.mdx +++ b/docs/how-to-reduce-your-spend.mdx @@ -24,20 +24,7 @@ Configure billing limits and alerts in your dashboard to protect against unexpec - Catch unexpected cost increases early - Identify runaway tasks before they become expensive -The **Billing limits** settings page has two sections: - -- **Billing limit**: Choose your plan limit, a custom amount, or no limit. When a limit is reached, billable environments (`production`, `staging`, and `preview`) enter a **grace period** — queues pause and new runs queue without starting. After grace expires, new triggers are rejected until you increase or remove the limit. -- **Billing alerts**: Add email alerts at specific spend thresholds (% of your limit when a limit is set, or dollar amounts when no limit is configured). Alerts notify you only; they do **not** pause environments or reject triggers. - -**Limits vs alerts:** A billing limit enforces spend (grace → reject). Billing alerts are optional notifications at thresholds you choose. - -**Soft limits:** Billing limits are not instantaneous hard caps. Usage is evaluated on a short delay, so spend can briefly exceed your limit before enforcement applies. Queued runs during grace incur no compute cost until they start. See our [terms](https://trigger.dev/terms) for refund policy details. - -On the **Usage** page, when you have a custom billing limit (or a plan limit that differs from included usage), a **Billing limit** marker appears on the usage bar alongside your current spend and plan included usage. - -![Billing limits and alerts settings](./images/billing-alerts-ui.png) - -You can open the page from the **Organization** menu in the top left of the dashboard, then **Settings** → **Billing limits**. +You can open the settings from the **Organization** menu in the top left of the dashboard, then **Settings** → **Billing limits**. [Read the full billing limits and alerts docs](/billing-limits) for how limits are enforced, the grace period, and resuming after hitting a limit. ## Reduce your machine sizes diff --git a/docs/limits.mdx b/docs/limits.mdx index 575e2a553f..d68760da10 100644 --- a/docs/limits.mdx +++ b/docs/limits.mdx @@ -7,6 +7,11 @@ import RateLimitHitUseBatchTrigger from "/snippets/rate-limit-hit-use-batchtrigg You can view your current limits, quotas, and rate limit usage in real-time by visiting the **Limits** page in the dashboard (accessible from the left sidebar). This page shows current rate limit token availability, quota usage, and plan features for your organization. + + Looking to cap your monthly spend? That's a setting you control, not a platform limit — see + [Billing limits and alerts](/billing-limits). + + ## Concurrency limits | Pricing tier | Limit | diff --git a/docs/troubleshooting.mdx b/docs/troubleshooting.mdx index fba6bf5c6b..e49fad49bb 100644 --- a/docs/troubleshooting.mdx +++ b/docs/troubleshooting.mdx @@ -242,6 +242,10 @@ If runs are staying in the `QUEUED` state for extended periods, check your concu - **Review queue concurrency limits** - Check if individual queues have restrictive `concurrencyLimit` settings - **Check for stuck runs** - See if stalled runs are blocking new executions +### Runs queued because a billing limit was reached + +If your organization has a [billing limit](/billing-limits) configured and your monthly spend reaches it, billable environments (`production`, `staging`, and `preview`) pause: new runs are still triggered and queued, but they won't start executing. Check the **Billing limits** page in your organization settings — increasing or removing the limit resumes execution. + ### `Crypto is not defined` This can happen in different situations, for example when using plain strings as idempotency keys. Support for `Crypto` without a special flag was added in Node `v19.0.0`. You will have to upgrade Node - we recommend even-numbered major releases, e.g. `v20` or `v22`. Alternatively, you can switch from plain strings to the `idempotencyKeys.create` SDK function. [Read the guide](/idempotency).