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 · Max · 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 a document under the same id can reuse unchanged content — token charges follow added or changed text, not simply growth in the document’s total length.

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	Gated v5 namespace search, v3/v4 search, and v4 profile calls that include a non-blank `q` query	queries
`sm_operations`	Operations	Counted platform operations not attributed to token or query meters: instant dreaming, and search add-ons such as query rewriting, reranking and aggregation	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" extracts a document’s memories immediately instead of waiting for the next dynamic batch. It costs one extra operation per document on top of normal token metering. See processing modes.
Search add-ons: query rewriting (rewriteQuery), reranking and aggregation (v5 rerank: "order" / "aggregate", v3/v4 rerank, v4 aggregate) each add one operation when they run successfully. Failed or skipped add-ons do not necessarily charge an operation.
Query-based POST /v4/memories/forget-matching adds one operation per search round, up to five, including dryRun previews. Applying an explicit ids list bypasses that query-operation charge.

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 /ns/{namespace}/search`, `supermemory.search()`	`sm_search_queries` (+1), plus `sm_operations` for any add-ons that run
`POST /ns/{namespace}/profile`, `supermemory.profile()`	No search-query meter in the current API implementation
Legacy `POST /v3/search`, `POST /v4/search`	`sm_search_queries` (+1), plus `sm_operations` for any add-ons that run
Legacy `POST /v4/profile` with a non-empty `q`	`sm_search_queries` (+1)

Blocking metered cloud calls can return 402 (payment required) when the applicable balance or quota is exhausted. Billing exclusions, unlimited contracts, disabled billing, and gate configuration can differ. The current v5 profile route does not install a search-query billing gate; this is not a guarantee of future pricing.

Reusing unchanged content (diff billing)

This is the most important cost control in production agents.

How it works

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

Loads the document’s active chunks and plans the updated content.
Reuses unchanged chunks where possible.
Meters newly appended text on an append path, or added replacement chunks on a replace path.

This is not a subtraction of the old total token count from the new one. A same-length replacement can still incur charges if its content changed; an identical replacement can reuse its chunks without new token charges. Chunk boundaries and overlap can also affect the billable delta. Stable IDs let long-lived conversations and repeated document syncs reuse unchanged work rather than billing the whole history every time. Operation surcharges can still apply.

Requirements

Requirement	Why
Stable `id`	Identity for “this is the same document.” Max length 255.
Same org / key	Documents are org-scoped.
Choose append or replace deliberately	Append meters the newly appended text; replace compares chunks and can reuse unchanged ones. Changed replacement chunks can bill even without net document growth.

Practical patterns

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

Connectors use stable IDs (e.g. Drive file id, Gmail thread id, s3://bucket/key), so re-syncs can reuse unchanged content. Changed replacement chunks can still incur token charges.

What is not free

First ingest of content still bills full token count
Gated searches still bill the query meter every call; legacy v4 profile does so only with a non-blank q. The current v5 profile implementation does not charge this meter.
Instant dreaming still bills the operation surcharge when used
Brand-new id = 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
Auto top-up purchase limits	Paid plans can limit automatic credit purchases per interval. This is not a hard cap on total usage or the full invoice.
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
Max	`api_max`	130 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	Plugins, API evaluation, prototypes
Pro	19 USD/mo	20 USD	Developers, core connectors
Max	100 USD/mo	130 USD	More usage headroom and Gmail
Scale	399 USD/mo	600 USD	Production, full connectors, teams
Enterprise	Custom	Contract	SSO, custom metering, FDE, air-gap

Feature availability

Feature	Free	Pro	Max	Scale	Enterprise
Memory API, search, profiles	Yes	Yes	Yes	Yes	Yes
Standard PDF extraction, including OCR for scans	Yes	Yes	Yes	Yes	Yes
Advanced document extraction for PDFs (figure and diagram descriptions)	—	—	—	Yes	Yes
Diff / delta token billing	Yes	Yes	Yes	Yes	Yes
Coding plugins (Claude Code, Codex, Cursor, OpenCode, OpenClaw, Hermes)	Yes	Yes	Yes	Yes	Yes
Team management	—	Yes	Yes	Yes	Yes
Google Drive, OneDrive, Notion, Granola connectors	—	Yes	Yes	Yes	Yes
Gmail connector	—	—	Yes	Yes	Yes
GitHub, S3, Web Crawler connectors	—	—	—	Yes	Yes
User Insights	—	—	—	Yes	Yes
Two-factor authentication	—	—	—	Yes	Yes
Org seat limit (members)	1	3	3	Unlimited	Unlimited
Auto top-up in the console	—	Yes	Yes	Yes	Contract
Auto top-up purchase limits	—	Yes	Yes	Yes	Contract
Custom metering / SSO / dedicated deploy	—	—	—	—	Yes

Coding plugins are available on every plan, including Free. Their API usage still consumes your plan’s credits at the applicable rates. PDF uploads use the extraction tier available to your organization automatically; no extra API parameter is required. On plans without advanced extraction, uploads still use standard extraction rather than returning a feature-gate error. Advanced extraction can also fall back to standard extraction if needed. This tier distinction applies to PDFs, not all supported file types. 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

Scoped API keys cannot read billing (403). GET /v3/auth/billing and POST /v3/auth/billing/auto-topups also require an org admin or owner. 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": { "balance": 14.62, "label": "USD" },
  "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
POST  /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 a stable id 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 a namespace so you can delete/export a tenant without scanning the org.
Configure auto top-up purchase limits on paid plans and monitor usage separately. These limits do not cap the entire invoice.
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 — id, 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

Reusing unchanged content (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 availability

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

​Reusing unchanged content (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 availability

​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

Reusing unchanged content (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 availability

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