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

# Quota and notifications tools

> MCP tools for inspecting your run balance and ledger, listing and acknowledging notifications, and updating notification preferences.

Check your organization's [run balance](https://docs.oqoqo.ai/setup/billing.md), read balance history, and manage your [notifications](https://docs.oqoqo.ai/setup/notifications.md).

* **Badges** are explained under [Approvals](https://docs.oqoqo.ai/mcp-server/overview.md#approvals).
* **Organization vs. project scope:** `inspect_quota`, `list_quota_ledger`, `inspect_notification_preferences`, and `manage_notification_preferences` are organization- or account-wide and do **not** take `project_id`. `list_notifications` and `acknowledge_notifications` act across every project in the organization when `project_id` is omitted.
* **`expected_organization_id`** is an optional string on every write tool, omitted from parameter tables; pass `organization.id` from [`get_identity`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_identity) ([Organization check](https://docs.oqoqo.ai/mcp-server/overview.md#organization-check)).
* **`limit`** values above a tool's maximum are capped, not refused.

## Tools

### inspect\_quota

**Get the run balance.** Returns the run balance, and whether a launch of `requested_runs` runs can start now. It offers no purchases or billing actions.

Read-only · CLI: [`oqoqo quota inspect`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-quota-inspect)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `requested_runs` | integer | No | Runs to check, 1 to 1,000,000. |

**Result fields**

`remainingRuns`, `reservedRuns`, `usedRuns`, `totalRuns`, `remainingBreakdown`, `state`, and `readiness`, as in [`oqoqo quota inspect`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-quota-inspect). The plugin returns no `billingUrl`.

### list\_quota\_ledger

**List run balance history.** Returns a page of run balance transactions. It offers no purchases or billing actions.

Read-only · CLI: [`oqoqo quota ledger`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-quota-ledger)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `types` | array of `grant`, `reserve`, `capture`, `release`, `expire`, `adjust` | No | Only these transaction types. |
| `limit` | integer | No | Results per page, up to 100 (default 50). |
| `cursor` | string | No | The `nextCursor` from the previous page. |

**Result fields**

Each entry has a `qtx_` `transactionId`, `type`, `amount`, `effectiveAt`, `expiresAt`, `source`, and the `experimentId` and link of the experiment that caused it, if any. `hasMore` and `nextCursor` page the list.

### list\_notifications

**List notifications.** Returns a page of your notifications, optionally for one project.

Read-only · CLI: [`oqoqo notifications list`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-notifications-list)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | Only this `prj_` project's notifications. Omit for all projects in the organization. |
| `status` | `all`, `unread` | No | All notifications, or unread ones only. |
| `limit` | integer | No | Results per page, up to 50 (default 25). |
| `cursor` | string | No | The `nextCursor` from the previous page. |

**Result fields**

Each notification has `notificationId`, `insertedAt`, `status`, `title`, and a safe link. A schedule's paused, skipping, and short-of-runs notices, and the problem notices of the experiments it launched, also carry its `scheduleId`, which you can read with `get_schedule`.

### acknowledge\_notifications

**Mark notifications as read.** Marks one notification, or up to 500 unread ones, optionally in one project. Repeating a call gives the same result.

Changes data · CLI: [`oqoqo notifications acknowledge`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-notifications-acknowledge)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `action` | `one`, `all` | Yes | Mark one notification, or a page of unread ones. |
| `notification_id` | string | With `one` | The notification to mark. |
| `limit` | integer | No | With `all`: notifications in one call, up to 500 (default 500). |
| `project_id` | string | No | Only this `prj_` project's notifications. Omit for all projects in the organization. |

**Result fields**

`acknowledgedCount` and, with `all`, `hasMore`. Repeat the call while `hasMore` is true.

### inspect\_notification\_preferences

**Get notification preferences.** Returns your account-wide setting for each category and channel, and whether each can be changed, is required, or doesn't apply.

Read-only · CLI: [`oqoqo notifications preferences`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-notifications-preferences)

This tool takes no parameters.

### manage\_notification\_preferences

**Change notification preferences.** Changes only the categories and channels you send. The rest stay as they are.

Changes data · CLI: [`oqoqo notifications preferences update`](https://docs.oqoqo.ai/cli/billing-and-notifications#oqoqo-notifications-preferences-update)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `patch` | object | Yes | Category keys, each set to `true` or `false` for every channel, or to an object of channels. |

| Category key | Channels |
| - | - |
| `experiment-updates` | `email`, `in-app` |
| `billing-updates` | `email`, `in-app` |
| `connection-alerts` | `email`, `in-app` |
| `product-marketing` | `email` |

For example, `{"experiment-updates": {"email": false, "in-app": true}}` keeps experiment updates in-app only.

## Related

> [card] [oqoqo quota and notifications](https://docs.oqoqo.ai/cli/billing-and-notifications.md)
>
> The matching CLI commands.

> [card] [Runs and billing](https://docs.oqoqo.ai/setup/billing.md)
>
> Plans, top-ups, and run balance rules.


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