> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing & usage

> Enterprise-grade reference for Supermemory metering — SM tokens, operations, search, SuperRAG, plans, diff billing, and programmatic usage APIs.

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 theme={null}
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)
```

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 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](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"`** — 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](/docs/ingestion/add-memories#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:

1. Loads the **previous extracted content** for that document
2. Computes **full** token count of the merged/updated document
3. Bills only:

```text theme={null}
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

```typescript theme={null}
// 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`

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

Typical fields:

```json theme={null}
{
  "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:

```bash theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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](/docs/overview/analytics).

### TypeScript sketch

```typescript theme={null}
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 stable `customId`** 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 **`containerTag`** so you can delete/export a tenant without scanning the org.
6. Enable **spend caps / auto top-up** on Scale for predictable production.
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](/docs/ingestion/add-memories) — `customId`, `dreaming`
* [Analytics](/docs/overview/analytics) — request-level observability
* [Security & compliance](/docs/overview/security) — trust posture for enterprise review