> 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/get-alerted-before-a-cap.md).

# Create a usage alert

Email Account Admins when credit usage crosses a threshold.

`POST /accounts/credits/usage-limit` with `type: "NotificationThreshold"` creates an alert. This is the API equivalent of [Create a usage alert](https://docs.uptiq.ai/platform-guides/admin/cost/create-a-usage-alert).

## 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

Emails Account Admins when credit usage reaches a threshold.
{% endcolumn %}

{% column %}

#### Success looks like

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

{% hint style="info" %}
**One endpoint, two purposes.** This is the exact same call as [Set a credit limit](/cookbooks/platform-admin/cost/cap-account-spending.md) — only `type` and the `metricType` field below differ. A hard limit rejects requests; a notification threshold only emails. Create both if you want the belt and the suspenders.
{% 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**, exactly as for the hard-limit call (see above).
* **At least one person must hold the Account Admin role.** The alert emails every Account Admin role holder and nobody else — this call succeeds even if no one holds that role, and the alert then reaches no one.
* If using `PercentageOfLimit`, create the matching-duration hard limit first — the percentage is measured against it. This is enforced: without one, the call returns **`400 — Percentage thresholds require a hard limit for the same duration`**. Note also that only one limit may exist per `type` + `duration`; a second `POST` into an occupied slot returns `400 — a hard limit already exists for <duration> duration`, and changing it means `PUT`.

## Request

`POST /accounts/credits/usage-limit`

| Field        | Type   | Required | What it does                                                                    |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------- |
| `type`       | string | Yes      | `NotificationThreshold` for this recipe.                                        |
| `duration`   | string | Yes      | `Daily`, `Weekly`, or `Monthly` — match this to the limit it watches.           |
| `metricType` | string | Yes\*    | `AbsoluteCredits` or `PercentageOfLimit`. Required for thresholds specifically. |
| `value`      | number | Yes      | Credit count for `AbsoluteCredits`; percent (1–100) for `PercentageOfLimit`.    |

## 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": "NotificationThreshold",
    "duration": "Monthly",
    "metricType": "PercentageOfLimit",
    "value": 80
  }'
```

{% 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: "NotificationThreshold",
    duration: "Monthly",
    metricType: "PercentageOfLimit",
    value: 80,
  }),
});
```

{% 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": "NotificationThreshold",
        "duration": "Monthly",
        "metricType": "PercentageOfLimit",
        "value": 80,
    },
)
```

{% endtab %}
{% endtabs %}

## Response

| Result          | What it means                                               | Next action                                 |
| --------------- | ----------------------------------------------------------- | ------------------------------------------- |
| ✅ `201 Created` | `data` includes the alert ID and the `metricType` you sent. | Store the ID for later updates or deletion. |

{% 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": "39bba930-9608-4a97-bcf8-8bedf82acc22",
    "accountId": "YOUR_ACCOUNT_ID",
    "type": "NotificationThreshold",
    "duration": "Daily",
    "metricType": "PercentageOfLimit",
    "value": 80
  }
}
```

{% hint style="warning" %}
**A percentage alert is owned by its hard limit.** Deleting the hard limit for that duration deletes this threshold with it, and a later `DELETE` of the alert then returns `404`. When tearing both down, delete the alert first.
{% endhint %}

## Developer notes

| Situation                 | What to do                                                                                                                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Delete an alert           | Send `DELETE /accounts/credits/usage-limit/{id}`. The service returns `204 No Content` with an empty body.                                                                                 |
| Choose thresholds         | Create one alert around 50% and another around 90%. An alert at 100% arrives when work starts failing.                                                                                     |
| Interpret alert frequency | Each alert fires once per period after the threshold is crossed. It doesn't fire for every later request.                                                                                  |
| Change alert recipients   | Change who holds the Account Admin role. Alerts target the role, not an address list. See [Change a user's roles](/cookbooks/platform-admin/give-people-access/change-someones-access.md). |

## Related

* [Create a usage alert](https://docs.uptiq.ai/platform-guides/admin/cost/create-a-usage-alert) — as a screen
* [Set a credit limit](/cookbooks/platform-admin/cost/cap-account-spending.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/get-alerted-before-a-cap.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.