# Plan and Usage

> Check your Mojeeb plan, this billing period's message and agent usage, and your past billing periods with GET /v1/organization/usage and GET /v1/organization/usage/history. Read-only.

Two read-only calls show where your organization stands. `GET /v1/organization/usage` returns your plan, your subscription's status and the billing period that covers now, with the messages and agents used against your limits. `GET /v1/organization/usage/history` lists the billing periods of your subscription. Both cover your whole organization, and neither returns prices or payment details.

## How do I check how many messages are left?

Call `GET /v1/organization/usage`.

```bash
curl https://api.mojeeb.app/v1/organization/usage \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

`messages.remaining` is what's left until `period.end`, when message usage starts again from zero. The limits include your add-ons; to raise them, see [Add-Ons](/docs/billing/add-ons). Every field is in the [Get your plan and current usage reference](../api-reference/get-usage).

## How do I see past billing periods?

Call `GET /v1/organization/usage/history`.

```bash
curl https://api.mojeeb.app/v1/organization/usage/history \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

Periods come newest first, each with the messages used against that period's limits, and `current: true` marks the one that covers now. See the [List usage by billing period reference](../api-reference/list-usage-history).

## What counts as a message?

Each time the AI answers or acts: every reply, every turn in which it runs a tool (even when it sends no text), and every tool run itself, such as saving a lead, booking, adding a sheet row, a Custom API call or a webhook. Files the AI sends, follow-ups and replies to comments count too, and so does a teammate's Capture Lead from a chat. When the agent has a lot of knowledge, each of these counts as more than one message; see [How much knowledge can I add?](/docs/features/knowledge-base#how-much-knowledge-can-i-add). Your team's replies and [WhatsApp broadcasts](/docs/channels/whatsapp-broadcasts) don't count, and neither, today, do WhatsApp messages and templates you send through the API. See [Plans and Pricing](/docs/billing/plans-and-pricing).

## Common questions

### Why is `used` higher than `limit`?

A reply from an agent with a lot of knowledge counts as several messages, so the last reply before the limit can take `used` past it. `remaining` stays at zero, and `percent` can pass 100.

### Why does a key limited to some agents see the whole organization's usage?

Your plan's allowance belongs to the organization, and every agent draws from it. The API has no per-agent split.

### What does `status` mean?

It's your subscription's status. `active` and `trialing` are in good standing; `past_due`, `paused`, `canceled` and `pending_payment` mean your subscription needs attention on the **My Subscription** page. New values may appear. See [Manage Subscription](/docs/billing/manage-subscription).

### What do `409 no_current_usage_period` and `409 usage_periods_overlap` mean?

Mojeeb can't name the one billing period that covers now, so it can't tell which limits apply. `no_current_usage_period` means no period covers now: Mojeeb treats the subscription as not renewed, and the AI doesn't reply until a period opens. It clears when the renewal lands. It is also the answer when your organization has no subscription at all. `usage_periods_overlap` means more than one period covers now. If either lasts, contact support with the response's `correlation_id`.

### Why doesn't the history go back to my first month?

It covers your current subscription only. Canceling starts a new subscription on the free plan, and the history starts again from there.

### Why do past periods have no agent count?

Agent usage isn't recorded per period. `GET /v1/organization/usage` has today's count.

### How often should I call it?

Usage changes with every AI reply, so every few minutes is plenty for a dashboard or an alert. These calls share your key's rate limit; see [Rate Limits](../rate-limits).

### Can I change my plan or buy add-ons through the API?

No. Do both on the **My Subscription** page; see [Manage Subscription](/docs/billing/manage-subscription) and [Add-Ons](/docs/billing/add-ons).

### Which scope do these calls need?

`usage:read`, which every key holds today; see [Authentication](../authentication).