Skip to main content

Plan and Usage

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.

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. Every field is in the Get your plan and current usage reference.

How do I see past billing periods?​

Call GET /v1/organization/usage/history.

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.

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?. Your team's replies and WhatsApp broadcasts don't count, and neither, today, do WhatsApp messages and templates you send through the API. See 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.

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.

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

No. Do both on the My Subscription page; see Manage Subscription and Add-Ons.

Which scope do these calls need?​

usage:read, which every key holds today; see Authentication.