supermemory/apps/docs/overview/billing.mdx

---
title: "Billing & usage"
description: "How Supermemory metering works: SM tokens, operations, search, SuperRAG, plans, diff billing and the usage APIs."
sidebarTitle: "Billing & usage"
icon: "/icons/hugeicons/credit-card.svg"
---

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](https://console.supermemory.ai).

List prices and the public rate card also live on [supermemory.ai/pricing](https://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.

<Note>
Console charts are **estimates**. Invoice / customer-portal line items are authoritative.
</Note>

## Mental model

```text
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)
```

1. You hold a **USD credit balance** (`usd_credits`).
2. Product activity increments **meters** (tokens, queries, operations).
3. Each meter unit multiplies by a **USD-per-unit** rate and debits the balance.
4. **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](https://supermemory.ai/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](/ingestion/add-memories#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.

---

<span id="full-discount-on-already-seen-tokens-diff-billing" />

## 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:

1. Loads the document's active chunks and plans the updated content.
2. Reuses unchanged chunks where possible.
3. 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

```typescript
// 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](/concepts/content-types#advanced-document-extraction) (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`

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

Typical fields:

```json
{
  "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:

```bash
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.

```bash
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.

```bash
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

```http
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](/overview/analytics).

### TypeScript sketch

```typescript
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)

1. **Always set a stable `id`** on conversations and docs so re-sync is free on old tokens.
2. Prefer **session-level** conversation documents over one-line micro-adds (better memory **and** less wasted processing).
3. Use **`dreaming: "instant"`** only when you need immediate memory (extra operation); default `"dynamic"` batches extraction.
4. Cache **profiles** short-TTL in your app if you call them every turn.
5. Scope with a **`namespace`** so you can delete/export a tenant without scanning the org.
6. Configure **auto top-up purchase limits** on paid plans and monitor usage separately. These limits do not cap the entire invoice.
7. Pull **`/v3/auth/billing/usage-events`** into your own FinOps dashboard for per-day Memory vs SuperRAG spend.

---

## Related

- [Pricing page](https://supermemory.ai/pricing) — live plan marketing rates
- [Console billing](https://console.supermemory.ai) — plan, invoices, top-ups
- [Add context](/ingestion/add-memories) — `id`, `dreaming`
- [Analytics](/overview/analytics) — request-level observability
- [Security & compliance](/overview/security) — trust posture for enterprise review