Skip to main content
Every FocusAlpha API key belongs to a plan. Every dataset is available on every plan, including Free — your plan determines how many credits you have to spend and how fast you can call the API. This page explains both.

​
Plans

The Free plan’s 100 credits never expire, but they also never renew — they are a trial allowance for evaluating the API. Professional and Fund balances reset to their full grant at the start of each billing period; unused credits do not roll over. For current pricing, see your account settings.

​
How credits are metered

The billing rule is deliberately simple:
1 call = 1 credit. Every metered request costs exactly one credit, flat, regardless of which dataset it hits or how much data it returns.
The credit is charged when your request is accepted, before the handler runs. If the request then fails — a validation error, a missing resource, a server fault — the charge is automatically refunded. You only pay for calls that return answers. One endpoint goes further: GET /v1/filings/items also refunds a successful response that carries no items (for example, a filing that could not be parsed into items). An answer-less 200 there costs nothing.

​
Free endpoints

Discovery and vocabulary endpoints cost 0 credits, so you can always enumerate what is available before spending anything: Two account endpoints are also free to call:
  • GET /v1/usage — your request totals for a period, broken down by key
  • GET /v1/_status — per-dataset coverage and freshness (see Coverage and freshness)

​
Dataset access

Every dataset — including screening, ETF data, live news and events, guidance, regional filings and the WebSocket event streams — is open to every plan. Credits and rate limits are the only difference between plans, so the Free plan’s 100 credits are a way to try any dataset before you upgrade.

​
When you run out of credits

A metered call with an empty balance returns 402 Payment Required:
  • On the Free plan the message is Free credits used up. Upgrade to keep making requests.
  • On a paid plan it tells you that you are out of credits for the current billing period.
See Errors for the envelope shape.
You will get a heads-up before hitting zero: when a paid balance drops to 10% or less of its grant, we send one email per billing period to the account owner.

​
Checking your consumption

GET /v1/usage is free and returns request totals for a date range (defaulting to the current month), broken down by API key prefix:
Your dashboard at app.focusalpha.ai shows the same numbers alongside your remaining credit balance.

Rate limits

Per-minute request ceilings by plan, and which endpoints enforce them.

Errors

Error envelopes and every status code the API returns.