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

# Budgets

> Every organization and namespace has a daily and monthly spend budget. See it, change it, and know what happens when work reaches it.

Every organization and every namespace has a spend budget from the moment it exists. A budget has a daily and a monthly period, in US dollars of metered usage. It counts all metered work in its scope: batch processing, extraction, and search-query inference.

You change budgets yourself, in [Studio](https://studio.mixpeek.com) or through the API. Two bounds apply:

* A namespace budget fits inside its organization's budget.
* An organization budget stays at or below your plan's safety ceiling. To go above the ceiling, contact Mixpeek support.

Every change records who made it, when, and the value it replaced.

## Defaults

A new organization starts with the default budget for its plan. Each namespace starts with its organization's namespace default. If your organization already set a monthly spending cap under [Billing](/docs/platform/billing#tracking-usage), that cap is its monthly budget until you set one here.

| Plan       | Daily budget | Monthly budget |
| ---------- | ------------ | -------------- |
| Free       | \$5          | \$25           |
| Build      | \$50         | \$1,000        |
| Scale      | \$200        | \$4,000        |
| Enterprise | \$500        | \$10,000       |

`GET /v1/organizations` returns the budget in effect as `spend_limits`, with spend to date and the headroom left. `GET /v1/namespaces/{namespace_id}` returns the namespace's as `budget`. Each field names its source, so you can tell a default from a value someone set.

## Set the organization budget

An organization admin sets the organization budget and the default every namespace gets. Send `null` for a field to return it to the plan default.

<CodeGroup>
  ```python Python theme={null}
  import requests

  resp = requests.patch(
      "https://api.mixpeek.com/v1/organizations",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "spend_limits": {
              "daily_usd": 40,
              "monthly_usd": 800,
              "namespace_default_daily_usd": 10,
          }
      },
  )
  print(resp.json()["spend_limits"])
  ```

  ```javascript JavaScript theme={null}
  const resp = await fetch("https://api.mixpeek.com/v1/organizations", {
    method: "PATCH",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      spend_limits: { daily_usd: 40, monthly_usd: 800, namespace_default_daily_usd: 10 },
    }),
  });
  console.log((await resp.json()).spend_limits);
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.mixpeek.com/v1/organizations \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"spend_limits": {"daily_usd": 40, "monthly_usd": 800, "namespace_default_daily_usd": 10}}'
  ```
</CodeGroup>

A value above your plan's ceiling returns `400` with the ceiling in the message.

## Set a namespace budget

<CodeGroup>
  ```python Python theme={null}
  import requests

  resp = requests.patch(
      "https://api.mixpeek.com/v1/namespaces/ns_your_namespace",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={"spend_budget": {"daily_usd": 5, "monthly_usd": 100}},
  )
  print(resp.json()["budget"])
  ```

  ```javascript JavaScript theme={null}
  const resp = await fetch("https://api.mixpeek.com/v1/namespaces/ns_your_namespace", {
    method: "PATCH",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ spend_budget: { daily_usd: 5, monthly_usd: 100 } }),
  });
  console.log((await resp.json()).budget);
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.mixpeek.com/v1/namespaces/ns_your_namespace \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"spend_budget": {"daily_usd": 5, "monthly_usd": 100}}'
  ```
</CodeGroup>

A namespace budget above its organization's budget returns `400`. Raise the organization budget first.

## At the limit

Work in a scope that has reached its budget behaves by kind:

* **New batches are refused.** The batch submit returns `403` with `type: "QuotaExceededError"`. The message names the budget and the period, and says how to raise it. `details.how_to_set_budget` holds the request that raises it.
* **Search keeps working.** Retrievers and query inference continue under a conservative request quota.
* **Scheduled triggers wait.** A trigger due while its scope is at a limit holds that firing and runs once the scope has room again. A held firing does not count as a failure.

A daily budget resets at 00:00 UTC. A monthly budget resets on the 1st at 00:00 UTC.

## Automatic safety limits

Mixpeek also applies limits you do not set, which protect against runaway spend:

* **Spend velocity.** A namespace or organization whose hourly spend jumps far above its own recent pattern is paused for new paid work. One trial run is admitted after 30 minutes. If spend stays normal, the pause lifts on its own.
* **Retries.** A failed batch is retried automatically at most 5 times. All attempts share one spend budget. A batch that spent on a paid model and wrote no documents is retried at most once.
* **Failing schedules.** A scheduled trigger pauses after 3 failed runs in a row. It makes one trial run per hour, and a successful run restores it.
* **Free plan automation.** A free organization without a payment method can hold 1 active scheduled trigger and 1 active bucket sync. Add a payment method in [Studio Billing](https://studio.mixpeek.com/billing) to run more.
* **Inactive accounts.** On an account with no sign-in or API activity for 14 days, scheduled triggers and syncs pause. The next API call or sign-in resumes them. Paid accounts are exempt.