---
title: "Limits & Quotas"
description: "Storage quota, send and API rate limits, content retention, and the per-account limits Primitive enforces. How to read your account's effective limits from the API."
canonical: "https://docs.primitive.dev/docs/limits"
last-updated: "2026-05-17T00:00:00.000Z"
---

# Limits & Quotas

Primitive enforces a small set of per-organization limits. Your account's effective limits are returned by the API, so you never have to hard-code them — read them at runtime and adapt.

For plan options and pricing, see the [pricing page](/pricing). This page documents the limits themselves and how to observe them.

## Read your effective limits

`GET /v1/account` returns a `limits` object alongside your plan and granted entitlements:


```
curl https://api.primitive.dev/v1/account \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY"
```


```
{
  "success": true,
  "data": {
    "plan": "developer",
    "entitlements": ["..."],
    "limits": {
      "storage_mb": 5120,
      "send_per_hour": 1000,
      "send_per_day": 10000,
      "api_per_minute": 3000,
      "webhooks_max_global": 1,
      "webhooks_per_domain": false,
      "filters_per_domain": false,
      "spam_thresholds_per_domain": false
    }
  }
}
```

FieldMeaning`storage_mb`Your plan's included stored-email storage, in MB. It is an allowance, not a cap: see `GET /v1/account/storage` (below) for usage, the enforced limit, and billed overage.`send_per_hour` / `send_per_day`Outbound send caps over a rolling hour and day.`api_per_minute`Authenticated v1 REST API request cap per organization per minute.`webhooks_max_global`Maximum endpoints across the org. `null` means unlimited.`webhooks_per_domain`Whether endpoints can be scoped per domain.`filters_per_domain`Whether allow/block [filters](/docs/endpoints) can be scoped per domain.`spam_thresholds_per_domain`Whether spam thresholds can be set per domain.

`webhooks_max_global` is `null` when unlimited. Treat any limit as plan-dependent and read it from this endpoint rather than assuming a fixed value.

## Storage

`GET /v1/account/storage` reports your stored-email usage against your plan's included storage, the limit at which mail is refused (if any), and the storage billed as overage:


```
curl https://api.primitive.dev/v1/account/storage \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY"
```


```
{
  "success": true,
  "data": {
    "used_bytes": 148897792,
    "used_kb": 145408,
    "used_mb": 142,
    "included_mb": 5120,
    "limit_mb": 10240,
    "overage_mb": 0,
    "search_index_bytes": 0,
    "quota_mb": 5120,
    "percentage": 2.8,
    "emails_count": 5120,
    "emails_count_capped": false
  }
}
```

FieldMeaning`included_mb`Storage included with your plan.`limit_mb`Storage at which inbound mail is refused. `null` on paid plans, which are never refused for storage.`overage_mb`Storage past `included_mb`, counting your mail and your search index. Paid plans are billed for it at the storage rate; on Developer it draws on your monthly credits.`search_index_bytes`Your semantic search index, billed as storage at a fixed 8 KiB per indexed chunk. It counts toward `included_mb` and `overage_mb`, never toward `limit_mb`.`emails_count`, `emails_count_capped`Emails still holding their stored content, counted up to 100,000. When `emails_count_capped` is `true` you have more, and `emails_count` is that floor.`quota_mb`, `percentage`The included allowance and your usage as a percentage of it (can exceed 100). Kept for existing clients; `quota_mb` equals `included_mb` and is not a limit.

Stored raw email and attachments count toward storage. To free space, [discard content](/docs/receiving) you no longer need.

## Payloads (large-file) storage

Primitive Payloads lets you send and receive files of any size by email (end-to-end encrypted, content-addressed), separate from the stored-email quota above. It is on by default for every organization, agent accounts included; the `payloads_enabled` entitlement in `GET /v1/account` reports whether it is on for yours.

- Transfer is free. You never pay for download bandwidth — egress is unlimited at every plan.

- Storage is billed at `$0.03` per GB-month. Because attachments are ephemeral by default, storage is measured over time (GB-months), so short-lived files barely count.

- Included storage per plan: Developer 5 GB, Power 10 GB, Platinum 50 GB. On Developer the allowance is a hard cap (new uploads are refused once it is full); paid plans bill storage beyond the included amount at the rate above.

## Content retention

Primitive does not delete your inbound email content on a schedule — stored raw email and attachments are retained until you remove them. When you want to delete content, you do it yourself with [content discard](/docs/receiving), which is irreversible. See the [Privacy Policy](https://www.primitive.dev/privacy) for the full data-handling and deletion terms.

## Rate limits

Developer, Power, and Platinum organizations can make up to 3000 authenticated v1 API requests per minute. Organization API keys, OAuth access tokens, and connected agent keys share this budget. Agent-tier organizations have a 120-per-minute budget. Requests without valid organization credentials have a separate 120-per-minute limit per IP. The `api_per_minute` value from `GET /v1/account` reports your organization's limit.

When you exceed a rate limit, the API responds with `429` (error code `rate_limited`, or `rate_limit_exceeded` on some per-resource limiters), plus `Retry-After` and `ratelimit-*` headers. Branch on the `429` status, not the code. See [Errors → Rate-limit responses](/docs/errors#rate-limit-responses) for the exact headers and the recommended back-off.

Outbound sends are additionally bounded by `send_per_hour` / `send_per_day`. These protect shared outbound IP reputation; if you have a legitimate higher-volume use case, contact support.

## Entitlement-gated features

Some capabilities are turned on per organization; many of them appear in the `entitlements` array from `GET /v1/account`. If a feature is not turned on, the relevant endpoint answers `feature_disabled` (`403`, `404` or `409`, depending on the endpoint). The message names the feature, and `error.details` usually carries `feature` (a stable id such as `access_mode`, `mailbox_access`, `roles`, `keys_api`, `interactions`, `wake_dispatch`, `mail_relay` or `recipient_routing`), `feature_name`, `enabled_by` (`primitive`) and `contact_email`. To turn a feature on for your organization, contact Primitive at the address given. The routing endpoints also include the missing entitlement and a `docs_url`. A few gated endpoints answer the generic `forbidden` error instead. Examples include per-domain filters and routes on paid plans.

## Related Pages

- [Errors](/docs/errors): the rate-limit envelope and headers.

- [Pricing](/pricing): plan options.

- [Sending Mail](/docs/sending): outbound caps and idempotency.

Maintained by the [primitive.dev team](/about) · [Trust & security](/trust)Last updated: May 17, 2026