Docs / Page

Rate Limits & Credits

Agentii uses a tiered credit model. Credits, not raw API calls, are the unit of consumption — reflecting the asymmetric cost of different data retrieval operations.

Credit Cost by Endpoint Category

Credit consumption is calculated per FR-001a. Categories reflect the computational cost of each operation.

Category	Endpoints	Credits
Lightweight metadata	search_companies, get_company_profile, list_domains, health, list_coverage, get_ticker_coverage, list_sources, list_xbrl_concepts, get_xbrl_fact, get_sec_filing, get_earnings_calendar_event, list_upcoming_earnings	1
Standard search	search_documents, search_sec_filings, search_xbrl_facts, search_earnings_calendar	1
Page map	read_source_outline	2
Keyword FTS	search_keyword_in_source	2
Deep labels surcharge	read_source_outline, search_keyword_in_source (with include_deep_labels=true)	+1
Page retrieval	read_source_pages	1 / page
Cross-period search	search_cross_period	1 / period
Unified search	search_unified	3
Batch search	batch_search	Σ sub-queries
Errors	HTTP 400, 401, 403, 404, 429, 503	0

Plan Tiers

Plan	Price	Monthly Credits	Extra Usage
Free Trial	$0	2,000 (7 days)	N/A
Starter	$19.90/mo	10,000	$0.005 / credit
Pro	$49/mo	50,000	$0.005 / credit
Enterprise	$199/mo	500,000	Custom

Rate Limit Behavior

Per-minute burst limits enforced via Redis ZSET sliding window algorithm.
When exceeded, the API returns 429 Too Many Requests with a Retry-After header specifying the wait time in seconds.
Rate limit status is returned in every response via X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
Credit consumption is returned in X-Credits-Consumed and X-Credits-Remaining headers on every authenticated response.

Credit Estimation

Estimate costs before executing expensive calls:

Page retrieval: Call read_source_outline first to get total_pages. Multiply by 1 credit/page for the read_source_pages call.
Cross-period: Each successful fiscal period costs 1 credit. Failed or unavailable periods cost 0.
Deep labels: Adding include_deep_labels=true adds +1 credit to the base cost.

See also: Getting Started · Error Codes · Authentication