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

# oqoqo quota and notifications

> Check your organization's run balance and its history, and list, acknowledge, and set your notifications from the terminal.

Check your organization's [run balance](https://docs.oqoqo.ai/setup/billing.md) before you launch, and manage your [notifications](https://docs.oqoqo.ai/setup/notifications.md). Buying runs stays in the dashboard: `oqoqo quota inspect` returns the **Usage & billing** link.

## oqoqo quota inspect

Show the run balance, and whether it covers a launch of a given size.

```bash theme={null}
oqoqo quota inspect [flags]
```

**Plugin (MCP) tool:** [`inspect_quota`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#inspect_quota)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--requested-runs` | integer | | Check whether the balance covers this many runs. At most 1,000,000. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Check whether you can launch 120 runs:

```bash theme={null}
oqoqo quota inspect --requested-runs 120
```

**Result fields**

| Field | Meaning |
| - | - |
| `remainingRuns` | Runs you can still use |
| `reservedRuns` | Runs held for work in progress |
| `usedRuns`, `totalRuns` | Runs used, and the total |
| `remainingBreakdown` | `planRuns`, `topUpRuns`, `otherRuns`, and `planResetsAt` |
| `state` | `unlimited`, `active`, `exhausted`, `expired`, or `none` |
| `readiness` | `canLaunch`, `requestedRuns`, `shortfallRuns`, and a `reason`: `unlimited`, `covered`, `insufficient`, `exhausted`, `expired`, or `not_provisioned` |
| `billingUrl` | The **Usage & billing** page, where you subscribe or top up |

**Notes**

Plan runs reset each billing period and don't roll over, and top-up runs never expire. A launch also checks the balance before it starts.

## oqoqo quota ledger

List the run balance history: every grant, hold, use, release, expiry, and adjustment.

```bash theme={null}
oqoqo quota ledger [flags]
```

**Plugin (MCP) tool:** [`list_quota_ledger`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#list_quota_ledger)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--type` | string | | Comma-separated types: `grant`, `reserve`, `capture`, `release`, `expire`, `adjust`. |
| `--limit` | integer | `50` | Results per page, up to 100 (default 50). |
| `--cursor` | string | | The `nextCursor` from the previous page. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

List the latest 20 entries as JSON:

```bash theme={null}
oqoqo quota ledger --limit 20 --output json
```

List only grants, uses, and releases:

```bash theme={null}
oqoqo quota ledger --type grant,capture,release
```

**Result fields**

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

## oqoqo notifications list

List your notifications in the current organization.

```bash theme={null}
oqoqo notifications list [flags]
```

**Plugin (MCP) tool:** [`list_notifications`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#list_notifications)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--status` | `all`, `unread` | `all` | Every notification, or only unread ones. |
| `--limit` | integer | `25` | Results per page, up to 50 (default 25). |
| `--cursor` | string | | The `nextCursor` from the previous page. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

List your unread notifications as JSON:

```bash theme={null}
oqoqo notifications list --status unread --output json
```

**Result fields**

Each item has `notificationId`, `insertedAt`, `status`, and `title`. A schedule's paused, skipping, and short-of-runs notices, and the problem notices of experiments it launched, also carry a `scheduleId` that you can read with [`oqoqo schedules get`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-get). When notifications aren't available, `reason` says why.

## oqoqo notifications acknowledge

Mark one notification, or a page of unread ones, as read.

```bash theme={null}
oqoqo notifications acknowledge (--id <notification-id> | --all) [flags]
```

**Plugin (MCP) tool:** [`acknowledge_notifications`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#acknowledge_notifications)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--id` | string | | Mark this notification as read. |
| `--all` | boolean | `false` | Mark up to `--limit` unread notifications as read. |
| `--limit` | integer | `500` | Notifications in one `--all` call, up to 500 (default 500). |

Pass `--id` or `--all`. Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Mark every unread notification as read:

```bash theme={null}
oqoqo notifications acknowledge --all
```

**Result fields**

The result gives `acknowledgedCount` and, with `--all`, `hasMore`.

**Notes**

You can run the command again safely. Repeat `--all` while `hasMore` is true.

## oqoqo notifications preferences

Show your **Email** and **In-app** choice for each notification category.

```bash theme={null}
oqoqo notifications preferences [flags]
```

**Plugin (MCP) tool:** [`inspect_notification_preferences`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#inspect_notification_preferences)

Takes only the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Show your notification preferences:

```bash theme={null}
oqoqo notifications preferences
```

**Result fields**

Each category has a cell for each channel: enabled, disabled, required, or not used. `manageUrl` links **Profile → Notifications**. Your choices apply in every organization.

| Key | Category | Channels you can change |
| - | - | - |
| `experiment-updates` | **Experiment updates** | `email`, `in-app` |
| `billing-updates` | **Billing and runs** | `email`, `in-app` |
| `connection-alerts` | **Connections and model providers** | `email`, `in-app` |
| `product-marketing` | **Product news and marketing** | `email` |
| `account-sign-in` | **Account and sign-in** | None (required) |
| `operational-alerts` | **Operational alerts** | None (required) |

## oqoqo notifications preferences update

Change one or more of your notification preferences.

```bash theme={null}
oqoqo notifications preferences update --patch <json> [flags]
```

**Plugin (MCP) tool:** [`manage_notification_preferences`](https://docs.oqoqo.ai/mcp-server/quota-and-notifications#manage_notification_preferences)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--patch` | string | | Required. JSON keyed by category. Each value is `true`, `false`, or an object with `email` and `in-app`. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Stop experiment update emails and keep them in the app:

```bash theme={null}
oqoqo notifications preferences update --patch '{"experiment-updates":{"email":false,"in-app":true}}'
```

Turn off product news:

```bash theme={null}
oqoqo notifications preferences update --patch '{"product-marketing":false}'
```

**Notes**

The patch takes the four categories you can change: `experiment-updates`, `billing-updates`, `connection-alerts`, and `product-marketing`, which has only `email`. Name at least one category, and at least one channel in each object. A category you leave out keeps its setting.

## Related

> [card] [Runs and billing](https://docs.oqoqo.ai/setup/billing.md)
>
> Plans, top-ups, and how runs are counted.

> [card] [Notifications](https://docs.oqoqo.ai/setup/notifications.md)
>
> The header inbox and Profile → Notifications.

> [card] [oqoqo experiments](https://docs.oqoqo.ai/cli/experiments.md)
>
> Preflight and launch once the balance covers it.

> [card] [oqoqo schedules](https://docs.oqoqo.ai/cli/schedules.md)
>
> Read the schedule a notice names.


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