Rate Limits and Quotas

API rate limits are the number of requests that you can make to the API within a specific time frame. The rate limits are set to ensure that the API is available to all users and to prevent abuse. If you exceed the rate limit, you will receive an error response with the status code 429 Too Many Requests.

TIP

The rate limits for the APITube News API are based on the plan you are subscribed to. You can view the rate limits for each plan below.

Rate limits

Rate limits are counted per account in a rolling 1-minute window — every live key you own shares one budget, so adding keys does not raise the ceiling. Test keys (api_test_) are counted in a separate bucket with their own limit.

Plan	Rate limit
Free	10 requests per minute, results limited to the first 5 pages
Starter / Basic / Professional	50 requests per minute
Corporate	200 requests per minute

Starter, Basic and Professional share the same 50 requests per minute limit — between them the difference is quota and features, not request throughput. Corporate is the one plan with a higher burst: 200 requests per minute. On the Free plan, requesting page 6 or beyond returns a 400 error with code ER0173.

Exceeding the per-minute limit returns a 429 error with code ER0203. Repeatedly exceeding it gets the key temporarily banned, returning 429 with code ER0204 until the ban window passes.

Results per page

per_page is capped by plan. The default is 100, clamped down to the plan ceiling — a Free request without per_page returns 10 articles and a Starter one returns 50, not 100.

Plan	Max per_page
Free	10
Starter	50
Basic	200
Professional	250
Corporate	250

Asking for more than the plan allows returns a 400 error with code ER0171 and a message naming the ceiling (Limit is out of range. Your plan allows up to 10 results per page.).

On the Free plan this compounds with the 5-page cap above: 5 pages × 10 articles means a Free key can reach at most 50 articles per query.

Title search window

A search that matches on article titles is limited to a 31-day published_at window. This is not a per-plan limit — it applies to every plan and every endpoint, including exports, SSE stream and WebSocket. It covers title, title_starts_with, title_ends_with, title_pattern and the boolean query parameter.

Request	Result
Title search without published_at.start / published_at.end	Last 31 days are searched. 200 with an ER0366 warning in meta.warnings and an x-query-window-clamped: 31 header
Title search with a range wider than 31 days	400 with code ER0110
Title search with a range of 31 days or less	Runs as requested
Any request without a title search	No range limit

Full-text search over titles is the most expensive query the API runs, and its cost scales with how many months of data the window touches — a one-year window reads roughly the whole article table. To search a longer period, issue one request per month-sized window. See Search window limit for examples.

Free plan delay

The Free plan is delayed by 12 hours: it returns articles published more than 12 hours ago, and never the newest ones. The delay is applied everywhere — search endpoints, aggregates, SSE and WebSocket streams and webhook deliveries — so a stream cannot be used to work around it. Paid plans (Starter and above) have no delay: an article is available as soon as it is indexed.

Two more Free-plan gates return 403 ER0706 instead of results: export formats other than JSON, and the Trends endpoint. See Plan gates for the full list.

Fact Check

The Fact Check endpoint (/v1/fact-check) has its own, stricter limit of 10 requests per minute — separate from the plan rate limit above — because every request runs language-model inference. It is also not available on the Free plan. Exceeding it returns a 429 error with code ER0203.

Natural language prompt

The prompt parameter is available on Basic and above. On Free and Starter it returns 403 ER0706 before the translation runs, so no points are spent.

Plan	prompt
Free	No
Starter	No
Basic	Yes
Professional	Yes
Corporate	Yes

This is the only limit that separates Starter from Basic in kind rather than in size. Everything else a prompt would build — the filters themselves, the boolean query language, every endpoint — is available on every plan; prompt only writes those filters for you, and each translation runs language-model inference.

SSE Stream Connections

Each plan has a limit on the number of concurrent SSE stream connections:

Plan	Max SSE Connections
Free	0
Starter	2
Basic	2
Professional	10
Corporate	50

If you exceed the limit, the API will return a 429 error with code ER0360.

Monitoring Rate Limits

APITube News API uses HTTP headers to provide information about your current rate limit status. The following headers are included in every API response:

Header	Description
X-RateLimit-Limit	The maximum number of requests you can make in the current time window
X-RateLimit-Remaining	The number of requests remaining in the current time window
X-RateLimit-Reset	The number of seconds remaining until the rate limit resets

Example (a paid plan with a 50 requests-per-minute limit):

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 49
X-RateLimit-Reset: 32

Account and quota headers

Every authenticated response also reports the state of the account itself, so you can track quota without calling /v1/balance separately:

Header	Description
X-Subscription-Plan	The key's plan (free, starter, basic, professional, corporate)
X-Points-Remaining	Points left in the current quota period
X-Balance-Remaining	Prepaid pay-as-you-go balance left, in cents
X-Budget-Remaining	Cents left in this month's PAYG spending limit — only present when a limit is set
X-Apitube-Mode	live or test, so an SDK never has to parse the test marker out of the content
X-Request-ID	Unique id of the request — quote it when contacting support

X-Points-Remaining reaching 0 is what turns the next request into 402 ER0176, and X-Budget-Remaining reaching 0 gives 402 ER0177. Watching either header lets you slow down before that happens.

X-Subscription-Plan: basic
X-Points-Remaining: 48500
X-Balance-Remaining: 0
X-Apitube-Mode: live
X-Request-ID: e5efb02a-d9bd-45e7-8264-829167dd4842

Pay-as-you-go spending limit

If you use pay-as-you-go billing, you can set an optional monthly spending limit on your account from the dashboard. It caps how much of your prepaid balance can be spent within a calendar month (UTC) — useful to protect your balance from an unexpected usage spike.

When a limit is configured, every response includes the remaining budget for the current month:

Header	Description
X-Budget-Remaining	Remaining monthly pay-as-you-go budget, in cents. Present only when a limit is set.

Example (50000 cents = $500 left this month):

X-Budget-Remaining: 50000

Once the monthly limit is reached, requests that would be billed to your balance are rejected with 402 and error code ER0177 until the limit resets at the start of the next month, or you raise/remove it in the dashboard. Requests covered by your plan quota are not affected.