> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/cookbooks/platform-admin/cost/cap-account-spending.md).

# Set a credit limit

Set a hard credit cap so an account cannot overspend.

`POST /accounts/credits/usage-limit` with `type: "HardLimit"` creates a cap. This is the API equivalent of [Set a credit limit](https://docs.uptiq.ai/platform-guides/admin/cost/set-a-credit-limit).

## At a glance

| Item              | Value                                           |
| ----------------- | ----------------------------------------------- |
| ⚙️ Microservice   | `Identity Hub`                                  |
| 🌍 Environment    | `QA`                                            |
| 🔗 Base URL       | `https://api-builder-qa.uptiq.dev/identity-hub` |
| ⌘ Endpoint        | `POST /accounts/credits/usage-limit`            |
| 🔐 Authentication | User session token                              |

{% columns %}
{% column %}

#### What it does

Sets an account-level hard cap on credit usage.
{% endcolumn %}

{% column %}

#### Success looks like

The service returns `201 Created` and the limit ID.
{% endcolumn %}
{% endcolumns %}

{% hint style="info" %}
**This is the same endpoint as** [**Create a usage alert**](/cookbooks/platform-admin/cost/get-alerted-before-a-cap.md)**.** One request shape, one field — `type` — decides whether you're creating a hard limit that rejects requests, or a notification threshold that only emails. Read that recipe too; it's easy to write one and assume you've covered both.
{% endhint %}

{% hint style="danger" %}
**An account API key cannot call this endpoint.** Verified against QA: with `x-platform-key` it returns **`404 USER_NOT_FOUND`** — the endpoint resolves the *calling user*, and an API key has no user behind it. Use a **user session token** instead, `authorization: Bearer <token>`, which expires one hour after issue.
{% endhint %}

## Before you start

* A **user session token** — not an account API key (see above). The user needs a role with the **Set credit limits** capability: Billing Manager, Account Admin, or Organisation Admin.
* Every account starts with a default weekly hard limit. Setting one here replaces it.

## Request

`POST /accounts/credits/usage-limit`

| Field      | Type   | Required | What it does                                                      |
| ---------- | ------ | -------- | ----------------------------------------------------------------- |
| `type`     | string | Yes      | `HardLimit` for this recipe.                                      |
| `duration` | string | Yes      | `Daily`, `Weekly`, or `Monthly`. Periods reset on UTC boundaries. |
| `value`    | number | Yes      | Credit count for the cap. Must be greater than 0.                 |

## Code snippets

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api-builder-qa.uptiq.dev/identity-hub/accounts/credits/usage-limit \
  -H "authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "type": "HardLimit", "duration": "Monthly", "value": 80000 }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
await fetch("https://api-builder-qa.uptiq.dev/identity-hub/accounts/credits/usage-limit", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.UPTIQ_SESSION_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({ type: "HardLimit", duration: "Monthly", value: 80000 }),
});
```

{% endtab %}

{% tab title="Python" %}

```python
import os, requests

requests.post(
    "https://api-builder-qa.uptiq.dev/identity-hub/accounts/credits/usage-limit",
    headers={
        "authorization": f"Bearer {os.environ['UPTIQ_SESSION_TOKEN']}",
    },
    json={"type": "HardLimit", "duration": "Monthly", "value": 80000},
)
```

{% endtab %}
{% endtabs %}

## Response

| Result          | What it means                       | Next action                                 |
| --------------- | ----------------------------------- | ------------------------------------------- |
| ✅ `201 Created` | `data.id` identifies the new limit. | Store it for later `PUT` or `DELETE` calls. |

{% hint style="success" %}
**Verified against QA on 22 September 2026.** Field names and nesting below are exactly as returned; identifiers and personal data are placeholders.
{% endhint %}

```json
{
  "message": "Credit usage limit created successfully",
  "data": {
    "id": "d9d7e5f3-c7e6-460a-8320-6a8003266188",
    "accountId": "YOUR_ACCOUNT_ID",
    "type": "HardLimit",
    "duration": "Daily",
    "value": 999999999
  }
}
```

## Developer notes

| Situation                           | What to do                                                                                                                                                   |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Record the configuration            | Keep your own record of who set the limit and why. The response only echoes request fields, `id`, and `accountId`.                                           |
| Update an existing limit            | Send `PUT`, not another `POST`. The service permits one limit per `type` and `duration`; a duplicate `POST` returns `400`.                                   |
| Set the right level                 | Set the account limit before inviting people. The strictest of organization, account, and agent limits wins. This call changes only the account-level limit. |
| Remove a limit                      | Send `DELETE /accounts/credits/usage-limit/{id}`. The service returns `204 No Content`.                                                                      |
| Remove a dependent percentage alert | Delete the alert first. Deleting its hard limit cascade-deletes the alert, so a later alert deletion returns `404`.                                          |
| Set another tenant's limit          | Use `/tenants/{id}/credits/usage-limit` as a super-admin. An ordinary account key can't use that variant.                                                    |

## Related

* [Set a credit limit](https://docs.uptiq.ai/platform-guides/admin/cost/set-a-credit-limit) — as a screen
* [Create a usage alert](/cookbooks/platform-admin/cost/get-alerted-before-a-cap.md)
* [Review credit usage](/cookbooks/platform-admin/cost/find-what-used-credits.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.uptiq.ai/cookbooks/platform-admin/cost/cap-account-spending.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.