Rate limits

smry meters two budgets independently: operations and fresh extractions. Every request spends an operation. Only a request that has to fetch an article from the open web spends a fresh extraction. Both are per account.

The numbers

	Free	Patron	Pro
Operations	60/min · 2,000/day	120/min · 10,000/day	120/min · 10,000/day
Fresh extractions	10/min · 100/day	30/min · 500/day	30/min · 500/day
Active API keys	2	5	20

Patron and Pro share the same request budgets. They differ on active API keys and on resource ceilings such as web monitors and storage.

Every signed-in account can create API keys, including the free plan. No upgrade is required to call the API.

Two budgets, one request

The two budgets are checked at different points, which is why a cache hit is cheap. The rules that follow from this:

Every operation charges the operation budget, including a 429-free cache hit and including GET /v1/me.
A cache hit costs an operation but not a fresh extraction. The cached read is attempted first, and the fresh-extraction budget is only checked after the cache misses.
An over-quota request never reaches the network, so it cannot populate the cache and then be retried into a success.
Four operations can spend a fresh extraction: POST /v1/articles/extract, POST /v1/articles/read, POST /v1/articles/search, and POST /v1/library/items when it carries a url. The save runs the same metered reader as an article read. Feeds, consumer, and every other library operation never spend one.

Reading the same URL twice costs two operations and one extraction. Saving it with POST /v1/library/items spends an extraction too when the URL is not cached — but only that first time. Every later read through GET /v1/library/items/{id}/content costs one operation and no extraction.

Quotas belong to the account, not the key

Published API quotas apply to the account, not independently to each of its credentials. Otherwise five active keys would silently multiply every advertised limit by five. — server/routes/developer-v1.ts

Creating more API keys does not raise any limit. A second key is for isolating a deployment so you can revoke it alone. Ten keys on one account share one 120-per-minute budget. The same holds for OAuth: every token issued for an account draws on that account’s single budget.

Response headers

Every response carries the operation budget’s current state:

Header	On	Value
`X-RateLimit-Limit`	Every response	The ceiling for the bucket that was checked.
`X-RateLimit-Remaining`	Every response	Requests left in that bucket. Never negative.
`Retry-After`	`429` only	Seconds to wait. Honour this exactly.
`X-RateLimit-Scope`	`429` only	`minute` or `daily` — which bucket ran out.

X-RateLimit-Scope is the field that decides your recovery. minute means wait under 60 seconds and continue. daily means stop the run and resume tomorrow; retrying in a loop will only burn the day’s budget confirming it is gone.

429 response

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Scope: minute
Content-Type: application/json

{
  "error": "API request limit reached. Contact support if you need more capacity.",
  "code": "rate_limit_exceeded",
  "retryAfter": 37
}

A fresh-extraction exhaustion looks different, and the difference matters:

429 from the extraction budget

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{
  "error": "Fresh extraction limit reached. Cached reads still work; contact support if you need more capacity.",
  "code": "extraction_limit_exceeded"
}

extraction_limit_exceeded does not mean the API is closed to you. Cached article reads, every library operation, and every feeds operation keep working. Branch on code — see Errors.

Read your own limits

GET /v1/me reports the limits and current usage for the authenticated account. Call it once at start-up and cache it for the run. Never hardcode plan numbers into application logic.

curl -sS "https://api.smry.ai/v1/me" \
  -H "Authorization: Bearer $SMRY_API_KEY"

import os
import httpx

response = httpx.get(
    "https://api.smry.ai/v1/me",
    headers={"Authorization": f"Bearer {os.environ['SMRY_API_KEY']}"},
)
response.raise_for_status()
me = response.json()

limits = me["limits"]
print(f"tier={me['tier']}")
print(f"operations: {limits['operationsPerMinute']}/min, {limits['operationsPerDay']}/day")
print(f"extractions: {limits['freshExtractionsPerMinute']}/min, {limits['freshExtractionsPerDay']}/day")

# Size your worker pool from the server's number, not a constant in your code.
concurrency = max(1, limits["freshExtractionsPerMinute"] // 3)

const response = await fetch("https://api.smry.ai/v1/me", {
  headers: { Authorization: `Bearer ${process.env.SMRY_API_KEY}` },
});
if (!response.ok) throw new Error(`GET /v1/me failed: ${response.status}`);

const me = (await response.json()) as {
  userId: string;
  tier: "free" | "premium" | "pro";
  limits: Record<string, number>;
};

// Size your worker pool from the server's number, not a constant in your code.
const concurrency = Math.max(1, Math.floor(me.limits.freshExtractionsPerMinute / 3));
console.log(me.tier, concurrency);

Response

200 OK

{
  "userId": "user_2abcDEF456ghi",
  "tier": "premium",
  "limits": {
    "activeApiKeys": 5,
    "rssSubscriptions": 1000,
    "rssSubscriptionsUsed": 41,
    "rssCollections": 100,
    "rssCollectionsUsed": 6,
    "webMonitors": 10,
    "webMonitorsUsed": 2,
    "webMonitorsRemaining": 8,
    "webMonitorMinimumIntervalMinutes": 60,
    "webMonitorMonthlyCredits": 720,
    "webMonitorMonthlyCreditsUsed": 88,
    "webMonitorMonthlyCreditsRemaining": 632,
    "libraryStorageBytes": 10737418240,
    "libraryStorageUsedBytes": 418447360,
    "libraryStorageRemainingBytes": 10318970880,
    "operationsPerMinute": 120,
    "operationsPerDay": 10000,
    "freshExtractionsPerMinute": 30,
    "freshExtractionsPerDay": 500
  }
}

tier is "free", "premium", or "pro". There is no "patron" value — the Patron plan reports as "premium". Compare against "premium", not the marketing name.

The *Used and *Remaining fields are live counts, not plan constants. They are the right input to a “should I create another monitor?” decision, and they save you a 409.

Active API keys

Plan	Active keys
Free	2
Patron	5
Pro	20

The ceiling counts active keys. Revoking a key frees its slot immediately. The current value for the authenticated account is limits.activeApiKeys in the response above. Create keys in the Developer console.

Staying under the limits

Read the limits once, at start-up

Call GET /v1/me and derive your concurrency from freshExtractionsPerMinute. A hardcoded constant goes stale the moment the account changes plan.

Serialize, do not fan out

Parallel requests hit the per-minute bucket together and all fail at once. A steady serial loop finishes sooner than a burst plus its backoff.

Save what you will re-read

Extraction is the scarce budget. POST /v1/library/items once, then read from the library as often as you like for the cost of an operation each.

Branch on X-RateLimit-Scope

minute means sleep and continue. daily means stop the run.

Never retry a permanent article failure

PAYWALL_ERROR and UNSUPPORTED_PUBLISHER spend an operation every time and never succeed. See Errors.

Need more capacity than the Pro numbers? Ask through support.

Errors

Every error code, including the two different 429s and what each means.

Read and search articles

Choose the operation that spends the least extraction budget.

Get started

Work with the API

Patterns

Reference

Rate limits

The numbers

Two budgets, one request

Quotas belong to the account, not the key

Response headers

Read your own limits

Response

Active API keys

Staying under the limits

Next

Errors

Read and search articles

​The numbers

​Two budgets, one request

​Quotas belong to the account, not the key

​Response headers

​Read your own limits

​Response

​Active API keys

​Staying under the limits

​Next

Errors

Read and search articles

The numbers

Two budgets, one request

Quotas belong to the account, not the key

Response headers

Read your own limits

Response

Active API keys

Staying under the limits

Next