Access and Quotas - Shumi Docs

Shumi meters natural-language queries. Everything else (typed endpoints, tool calls, screeners) is metered separately and far more loosely.

Tiers

Tier	Price	Query allowance
Free	Free	10 to start, then 1 per day, permanently
Plus	$20 / month	50 per day
Pro	$200 / month	No limit
Genesis	$500 once	Pro, for the lifetime of Shumi

You can also get one anonymous query before signing in at all. Genesis is gated. Claiming it requires holding 3,000,000 $SHUMI on Base. The check runs server-side at purchase; an order from a wallet below the threshold is refunded automatically. It is not a soft prompt.

How the free tier actually counts

This is the part that is usually described wrongly, including by an earlier version of these docs. Free is not a daily allowance of N. It is a lifetime grant of 10 queries attached to your account, and once that grant is spent you get one query per day, forever, at no cost. The grant does not refill. The daily drip never stops. The two counters behave differently on purpose:

	Resets
Free lifetime grant	Never. It is a running total against a fixed ceiling.
Free daily drip	Midnight UTC
Plus daily allowance	Midnight UTC

So a free account that has been idle for a year still has whatever remains of its original ten, plus today’s one, not eleven, and not zero.

Unlocking with $SHUMI instead

Holding $SHUMI on Base grants a tier without a subscription. No purchase, no recurring charge; the hold is the entitlement, and it lapses if you sell.

Hold	Grants
100,000 $SHUMI	Plus
1,000,000 $SHUMI	Pro
3,000,000 $SHUMI	Qualifies you to claim Genesis

For Plus and Pro the hold is an alternative path. You may subscribe with a card instead. For Genesis it is a hard requirement, and holding it qualifies you to buy; it does not grant Genesis by itself. When you hold and subscribe, the higher tier wins. Entitlements resolve across every source and the best one applies; they do not stack into a larger allowance.

Checking what you actually have

Tier is resolved from your entitlement, not inferred from your credential. The same resolver that answers this endpoint is the one the gate enforces, so the two cannot disagree:

curl https://api.shumi.ai/api/cli/billing/tier \
  -H "Authorization: Bearer $SHUMI_TOKEN"

{
  "schemaVersion": 1,
  "data": {
    "tier": "pro",
    "source": "shumi_hold",
    "expiresAt": null,
    "identity": { "kind": "apiKey", "userId": 1042, "walletAddress": "0x…" }
  }
}

source tells you why you have the tier, which matters when you have more than one path active:

`source`	Meaning
`free`	No entitlement beyond the free tier
`shumi_hold`	Granted by your $SHUMI balance on Base
subscription	An active monthly subscription
lifetime purchase	Genesis, bought once
`manual`	Granted directly

The two purchase sources carry the payment provider’s name inside the literal string. Read the value from this endpoint rather than hardcoding it: the meaning is stable, the spelling is not.

The paid entry tier is Plus everywhere a person reads it, and access in the tier field. The wire name predates the display name and is kept rather than migrated, per the rule on the Glossary. Match on access, print “Plus”.

When the quota runs out

Ask queries return 429 RATE_LIMITED with the used and limit values in error.details. Typed endpoints are metered separately and are not consumed by ask queries. Streaming is the exception worth knowing: GET /api/cli/watch/{stream} holds a connection open, which makes it the most expensive route on the surface, and it requires a paid tier rather than being purchasable per call. Exhausted free quota gets 429 there, not a partial stream.

API Overview, the envelope and error contract
Quickstart, getting a key
Glossary, why access and Plus are both correct

​Tiers

​How the free tier actually counts

​Unlocking with $SHUMI instead

​Checking what you actually have

​When the quota runs out

​Related

Tiers

How the free tier actually counts

Unlocking with $SHUMI instead

Checking what you actually have

When the quota runs out

Related