Usage & Limits

Understand how usage is tracked, quota limits per plan, and how to monitor your consumption.

How usage is tracked

CLAIV Memory tracks usage across several dimensions per billing cycle:

Ingest events

Number of messages ingested. Each POST /v6/ingest counts as one ingest event, even if the result is deduped: true.

Recalls

Total calls to POST /v6/recall. Recalls are unlimited on all plans.

Work units

Internal compute units consumed by enrichment processing. Varies by event length and complexity.

Tokens

Total tokens processed across recall synthesis responses — measured from the size of each llm_context.text response.

Plan limits

Metric	Free	Starter	Growth	Scale	Enterprise
Monthly ingests	200	5,000	20,000	75,000	Custom
Monthly recalls	Unlimited	Unlimited	Unlimited	Unlimited	Unlimited
Projects	1	3	10	25	Unlimited
Chat credits	50K	500K	2M	5M	Custom
Overage rate	Hard cap	$6/1K	$5/1K	$4/1K	≤$4/1K

All plans include unlimited recalls. You only pay based on ingest volume. The Free plan has a hard cap at 200 ingests — no overage billing.

Quota enforcement

When you exceed a quota, the API returns a 429 status with a structured error:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly ingest limit exceeded",
    "request_id": "req_abc123",
    "details": {
      "plan": "free",
      "reset_date": "2026-04-01T00:00:00Z",
      "usage": {
        "ingest_events": 200,
        "limit": 200
      }
    }
  }
}

Quotas reset on the first day of each billing cycle. Check your current usage in the dashboard or via the usage API endpoints.

Quota warning headers

When usage reaches 80% of any limit, the API adds warning headers to every response:

Header	Description
`X-Quota-Warning`	Set to approaching_limit when any metric reaches 80%.
`X-Quota-Ingests-Pct`	Percentage of monthly ingest quota used (e.g. 85).
`X-Quota-Reset-Date`	ISO 8601 date when the quota resets.

Use these headers to proactively warn users before they hit 429 errors. When a limit is unlimited, remaining will be null in the API response.

Monitoring usage

There are two ways to monitor your usage:

Dashboard

Open any project from your dashboard and click the Usage & Limits tab. Visual quota progress bars, per-endpoint breakdown, and range selection (today, 7d, 30d, this month).

Usage API

Programmatically check usage:

GET /v1/usage/summary — totals for the current billing period
GET /v1/usage/breakdown — per-day metrics for the current period
GET /v1/usage/limits — current quota status with remaining allowances

GET /v1/usage/limits — example response

{
  "rate_limits": {
    "ingest_per_minute":  500,
    "recall_per_minute":  200,
    "forget_per_minute":   60
  },
  "monthly_quotas": {
    "ingests": { "used": 180, "limit": 200, "remaining": 20 },
    "recalls": { "used": 4200, "limit": null, "remaining": null }
  },
  "overage_policy": "hard_stop"
}

Rate limits

In addition to monthly quotas, per-minute rate limits prevent burst abuse. When you exceed a rate limit you receive a 429 rate_limited response with a Retry-After header indicating seconds to wait.

Endpoint	Requests / min
POST /v6/ingest	500
POST /v6/recall	200
POST /v6/forget	60
GET /v1/usage/*	120

Getting started

Create a project and generate an API key from the API Keys page.

npm install @claiv/memory or pip install claiv-memory

200 free ingests per month — unlimited recalls. No credit card required.

Continue reading

Full API reference — usage endpoint schemas Troubleshooting quota errors and rate limits