Billing & usage

Supermemory billing is usage-based USD credits. Plans include a monthly credit balance; metered product usage draws that balance down. You manage plan, invoices, top-ups, and auto top-up in the Developer Console. List prices and the public rate card also live on supermemory.ai/pricing. This page is the contract-level model: what we meter, when tokens are free (already seen), what an operation is, plan feature gates, and how to read usage programmatically.

Console charts are estimates. Invoice / customer-portal line items are authoritative.

Mental model

PLAN (Free · Pro · Scale · Enterprise)
     │  includes monthly USD credits
     ▼
USD CREDIT BALANCE  ──draw──►  METERS
                                 ├── sm_tokens_text / sm_tokens_rich     (Memory ingest)
                                 ├── sm_superrag_text / sm_superrag_rich (SuperRAG task)
                                 ├── sm_search_queries                  (Search / profile)
                                 └── sm_operations                      (platform ops)

You hold a USD credit balance (usd_credits).
Product activity increments meters (tokens, queries, operations).
Each meter unit multiplies by a USD-per-unit rate and debits the balance.
Re-ingesting the same document under the same customId only bills the net-new token delta — already-seen content is effectively fully discounted.

Meters (what we count)

Feature ID	UI label	What counts	Unit
`sm_tokens_text`	Memory tokens (text)	Billable new tokens on Memory-path ingest for text-like content (`text`, `tweet`, `github_markdown`)	tokens
`sm_tokens_rich`	Memory tokens (rich)	Billable new tokens on Memory-path ingest for multimodal / extraction-heavy types (PDF, media, etc.)	tokens
`sm_superrag_text`	SuperRAG tokens (text)	Billable new tokens when the task type is SuperRAG (text)	tokens
`sm_superrag_rich`	SuperRAG tokens (rich)	Billable new tokens when the task type is SuperRAG (rich)	tokens
`sm_search_queries`	Search queries	Each search / profile call that runs retrieval (v3 search, v4 search, v4 profile with search)	queries
`sm_operations`	Operations	Counted platform operations not fully attributed to token meters (e.g. certain ingest modes such as instant dreaming, and other non-token platform actions)	operations

List rates (USD)

These match the console meter table (USD per unit; ×1000 ≈ price per 1K units):

Meter	USD per unit	Approx per 1K units
`sm_tokens_text`	0.000005	0.005 USD / 1K tokens
`sm_tokens_rich`	0.00001	0.010 USD / 1K tokens
`sm_superrag_text`	0.000001	0.001 USD / 1K tokens
`sm_superrag_rich`	0.000002	0.002 USD / 1K tokens
`sm_search_queries`	0.000005	0.005 USD / 1K queries
`sm_operations`	0.0001	0.10 USD / 1K operations

Rates can change; treat pricing + your invoice as source of truth.

Memory vs SuperRAG tokens

Ingestion is attributed by task type:

Memory (taskType: "memory") → sm_tokens_text / sm_tokens_rich
SuperRAG (taskType: "superrag") → sm_superrag_text / sm_superrag_rich

Text-like document types bill on the text meters; everything else bills as rich (OCR, video/audio, heavy extractors).

What is an operation?

sm_operations is the meter for discrete platform work that is not “how many tokens did we embed.” Examples include:

dreaming: "instant" — processes a document’s memory extraction immediately (does not wait for dynamic batch dreaming). Documented as one extra operation per document on top of normal token metering. See Processing modes.
Other non-token platform actions the product attributes to the operations meter (console: “counted platform operations not attributed to token or search meters”).

Search is primarily metered as sm_search_queries (one unit per gated search/profile request). Prefer thinking of operations as extra platform work, not as a synonym for “API call.”

Search and profile

Call	Typical meter
`POST /v3/search`, `POST /v4/search`, `client.search.*`	`sm_search_queries` (+1)
`POST /v4/profile` when it runs retrieval	`sm_search_queries` (+1)

If the org is out of balance, search/profile can return 402 (payment required) depending on gate configuration.

Full discount on already-seen tokens (diff billing)

This is the most important cost control in production agents.

How it works

When you re-add content under the same customId (same org / document identity), the pipeline:

Loads the previous extracted content for that document
Computes full token count of the merged/updated document
Bills only:

billableTokens = max(0, fullTokenCount - previousTokenCount)

So tokens Supermemory has already processed are not billed again. Unchanged content is a full discount on the token meters. Only the net-new delta (and any new rich extraction on that delta) draws credits. This is why long-lived agent loops stay cheap: re-sync the same conversation customId, re-upload the same policy doc, or connector re-sync with stable IDs — you pay for new material, not the whole history every time.

Requirements

Requirement	Why
Stable `customId`	Identity for “this is the same document.” Max length 255.
Same org / key	Documents are org-scoped.
Update path, not full replace	Full replace clears previous content for billing purposes (`isFullReplace` treats previous tokens as 0). Prefer append/update with the same `customId` for chat.

Practical patterns

// Session stays one document — only new turns bill tokens
await client.add({
  content: "user: " + msg + "\nassistant: " + reply,
  containerTag: userId,
  customId: "chat_" + sessionId, // stable for the session
  dreaming: "instant", // optional: +1 operation, faster memory
});

Connectors already use stable IDs (e.g. Drive file id, Gmail thread id, s3://bucket/key) so re-syncs diff-bill automatically.

What is not free

First ingest of content still bills full token count
Search / profile still bill query meters every call
Instant dreaming still bills the operation surcharge when used
Brand-new customId = brand-new document = full tokens

Credits and balance behavior

Concept	Behavior
Included plan credits	Monthly USD allowance tied to the plan (resets each billing period; no rollover)
Top-up credits	Purchased USD credits (console presets e.g. 10 / 25 / 50 / 100 USD). Persist until used (do not expire with the calendar month the way subscription inclusion does)
Spend order	Plan inclusion is consumed before top-up balance (Autumn merges both into `usd_credits`)
Auto top-up	Configurable in console for paid plans — adds credits when balance is low
Spend caps	Scale+ supports hard caps so usage cannot run away
Depleted balance	Metered APIs may block (e.g. 402) until top-up or period reset

Plan credit inclusion (approximate)

Plan	Product ID	Included credits / month
Free	`api_free`	5 USD
Pro	`api_pro`	20 USD
Scale	`api_scale`	600 USD
Enterprise	`api_enterprise`	Custom / unlimited by contract

Legacy product IDs (memory_free, memory_starter, memory_growth, memory_enterprise) still resolve for existing customers.

Plans and feature access

Usage meters are shared; feature gates differ by tier.

Plan summary

Plan	Price (list)	Included credits	Best for
Free	0 USD	5 USD	Evaluate API, prototypes
Pro	19 USD/mo	20 USD	Developers, plugins, core connectors
Scale	399 USD/mo	600 USD	Production, full connectors, teams
Enterprise	Custom	Contract	SSO, custom metering, FDE, air-gap

Feature matrix (code gates)

Feature	Free	Pro	Scale	Enterprise
Memory API, search, profiles	Yes	Yes	Yes	Yes
Diff / delta token billing	Yes	Yes	Yes	Yes
Plugins (Claude Code, Cursor, Hermes, …)	—	Yes	Yes	Yes
Team management	—	Yes	Yes	Yes
Google Drive, OneDrive, Notion connectors	—	Yes	Yes	Yes
Gmail, GitHub, S3, Web Crawler connectors	—	—	Yes	Yes
User Insights	—	—	Yes	Yes
Org seat limit (members)	1	3	Unlimited	Unlimited
Auto top-up	Limited	Yes	Yes	Contract
Spend caps	—	—	Yes	Contract
Custom metering / SSO / dedicated deploy	—	—	—	Yes

Overrides can be applied per org in metadata (featureOverrides) for enterprise deals.

HTTP behavior when gated

403 — plan too low for a feature (e.g. connector not on Free)
402 — quota / credits exhausted for a metered call (search, tokens, etc.)

Programmatic access

All of the following require an org-admin capable credential. Scoped API keys cannot read billing (403). Base: https://api.supermemory.ai
Auth: Authorization: Bearer YOUR_API_KEY

Summary — plan + high-level usage

GET /v3/auth/billing

curl -s https://api.supermemory.ai/v3/auth/billing \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

Typical fields:

{
  "plan": "pro",
  "usage": {
    "tokens": { "used": 120000, "limit": 0 },
    "queries": { "used": 4200, "limit": 0 }
  },
  "credits": {},
  "resetDate": "2026-08-01T00:00:00.000Z",
  "orgName": "Acme",
  "billingEmail": "billing@acme.com"
}

CLI:

npx supermemory billing show
npx supermemory billing usage

Feature breakdown (Autumn features)

GET /v3/auth/billing/usage Returns per-feature used / limit / unit for the org’s Autumn customer features (including usd_credits, token meters, search, operations), plus period bounds when available.

curl -s https://api.supermemory.ai/v3/auth/billing/usage \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

Meter events (day × feature)

GET /v3/auth/billing/usage-events Optional query: ?start=<ISO>&end=<ISO> to override the billing period.

curl -s "https://api.supermemory.ai/v3/auth/billing/usage-events" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

Response includes byFeature, byDay, memoryTotal, superragTotal, period start/end.

Auto top-up config

GET  /v3/auth/billing/auto-topups
PATCH /v3/auth/billing/auto-topups

Invoices

GET /v3/auth/billing/invoices

Product / request analytics (not the same as USD meters)

For request volume, errors, and per-key traffic (ops monitoring, not USD ledger): GET /v3/analytics/usage?period=24h|7d|30d See Analytics.

TypeScript sketch

const headers = {
  Authorization: "Bearer " + process.env.SUPERMEMORY_API_KEY,
};

const billing = await fetch("https://api.supermemory.ai/v3/auth/billing", {
  headers,
}).then((r) => r.json());

const usage = await fetch("https://api.supermemory.ai/v3/auth/billing/usage", {
  headers,
}).then((r) => r.json());

const events = await fetch(
  "https://api.supermemory.ai/v3/auth/billing/usage-events",
  { headers },
).then((r) => r.json());

console.log({
  plan: billing.plan,
  resetDate: billing.resetDate,
  usage,
  events,
});

Cost control checklist (production)

Always set stable customId on conversations and docs so re-sync is free on old tokens.
Prefer session-level conversation documents over one-line micro-adds (better memory and less wasted processing).
Use dreaming: "instant" only when you need immediate memory (extra operation); default "dynamic" batches extraction.
Cache profiles short-TTL in your app if you call them every turn.
Scope with containerTag so you can delete/export a tenant without scanning the org.
Enable spend caps / auto top-up on Scale for predictable production.
Pull /v3/auth/billing/usage-events into your own FinOps dashboard for per-day Memory vs SuperRAG spend.

Pricing page — live plan marketing rates
Console billing — plan, invoices, top-ups
Add context — customId, dreaming
Analytics — request-level observability
Security & compliance — trust posture for enterprise review

Getting Started

Concepts

Using supermemory

Deployment

Other resources

Migration Guides

Mental model

Meters (what we count)

List rates (USD)

Memory vs SuperRAG tokens

What is an operation?

Search and profile

Full discount on already-seen tokens (diff billing)

How it works

Requirements

Practical patterns

What is not free

Credits and balance behavior

Plan credit inclusion (approximate)

Plans and feature access

Plan summary

Feature matrix (code gates)

HTTP behavior when gated

Programmatic access

Summary — plan + high-level usage

Feature breakdown (Autumn features)

Meter events (day × feature)

Auto top-up config

Invoices

Product / request analytics (not the same as USD meters)

TypeScript sketch

Cost control checklist (production)

​Mental model

​Meters (what we count)

​List rates (USD)

​Memory vs SuperRAG tokens

​What is an operation?

​Search and profile

​Full discount on already-seen tokens (diff billing)

​How it works

​Requirements

​Practical patterns

​What is not free

​Credits and balance behavior

​Plan credit inclusion (approximate)

​Plans and feature access

​Plan summary

​Feature matrix (code gates)

​HTTP behavior when gated

​Programmatic access

​Summary — plan + high-level usage

​Feature breakdown (Autumn features)

​Meter events (day × feature)

​Auto top-up config

​Invoices

​Product / request analytics (not the same as USD meters)

​TypeScript sketch

​Cost control checklist (production)

​Related

Mental model

Meters (what we count)

List rates (USD)

Memory vs SuperRAG tokens

What is an operation?

Search and profile

Full discount on already-seen tokens (diff billing)

How it works

Requirements

Practical patterns

What is not free

Credits and balance behavior

Plan credit inclusion (approximate)

Plans and feature access

Plan summary

Feature matrix (code gates)

HTTP behavior when gated

Programmatic access

Summary — plan + high-level usage

Feature breakdown (Autumn features)

Meter events (day × feature)

Auto top-up config

Invoices

Product / request analytics (not the same as USD meters)

TypeScript sketch

Cost control checklist (production)

Related