Skip to main content
Every FocusAlpha API key belongs to a plan. Your plan determines three things: how many credits you have to spend, how fast you can call the API, and which datasets you are entitled to at all. This page explains all three.

​
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 entitlements

Credit cost is one axis; which datasets your plan may call at all is a separate one. Core SEC data is open to every plan, including Free. Differentiated datasets require Professional or Fund: Calling a dataset above your tier returns 402 Payment Required with a message naming the dataset and the plan it requires — Professional refusals include the upgrade URL, Fund refusals ask you to contact sales.

​
When you run out of credits

A metered call with an empty balance also 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.
The two 402 cases — out of credits versus not entitled — carry different messages, so your error handling can distinguish “top up or wait for renewal” from “this dataset needs a higher tier”. See Errors for the envelope shapes.
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.