Plans, limits, and what happens when one runs out.

The four things a plan meters

Everything else — searching, browsing the directory, reading a list page, looking at a provider — is unmetered. What your own plan includes is on the pricing page; the figures are kept there rather than repeated here, so there is one place to maintain and no chance of two pages disagreeing.

Why rows and calls are two numbers

Calls are pace and shape: how many times your system may ask us something this month. Rows are volume: how much of the data that leaves with the answers. They are different questions, so a plan states both, and a plan is never out of one because of the other.

The practical consequence is worth spelling out. A page of results costs one call and as many rows as it returned, so a page of fifty is fifty rows and a page of twelve is twelve. Asking for a page bigger than the rows you have left is refused rather than shortened — ask for a page that fits and you get it whole. Reading one record costs one row, an empty result costs none, and a lookup that finds nothing costs the call and no rows. Counts, place lists, specialty lists and published list pages name no record at all and cost no rows.

Reveals are priced as reveals and never also as rows, and a work email arriving in an ordinary API row is not a reveal and never touches that allowance. Nothing is charged twice: starting an export costs a call and no rows, the rows are charged when the file is written, and downloading that file again costs neither.

Why a procedure line is a row

A record about a provider costs a row wherever it leaves, and a published procedure or prescribing line is a record about a provider — it is the part of the answer that took the work, and the part somebody would otherwise have exported. So through the API it is metered as one, on the same monthly number an export spends, and the same refusal applies: ask for a page bigger than the rows you have left and it is refused rather than shortened. On screen in the app it is included, like search.

A file is priced differently, and the difference is the point of it. A file has one row per provider, so it carries a summary of a provider’s lines — the highest-volume few, and the sizes — rather than the lines themselves. Those columns widen a row; they never add one. An export or an append of ten thousand providers costs ten thousand rows with every one of them switched on, exactly as it does with none, and a provider with nothing published costs the row they were always going to cost because they are in the file either way. The per-line price stays on the API, where a line is what you asked for.

Two consequences are in your favour, and worth knowing before you plan a run. Asking about a provider with no published Medicare volume costs the call and nothing else, which matters because most clinicians have none — the data covers about one in six. And the two pickers that let you search “knee replacement” rather than a code are free of rows entirely, so building the query costs nothing and only the answer does.

What this data is, and what it is not: published Medicare fee-for-service volume for one year, not all-payor claims, with low-volume providers removed before publication. The full limits are on the data page, and they are worth reading before you budget against it.

Seats and alerts are features, not meters

A plan also says how many people can be in your organization and how many standing alerts it can keep. Those are limits on what exists rather than on what you spend, so they do not reset with the month.

A paid plan also has a daily cap

Beside the month, every paid plan carries a cap on rows, reveals and API calls for one day — roughly a tenth of the month, so one afternoon cannot spend it. It is a separate limit and the smaller of the two is what refuses, so a refusal names which one it was: a day resets at midnight UTC and your month is not spent, and the balance panel in the app shows both numbers side by side rather than making you work it out.

Appended rows have no daily cap, on purpose: an append is weighed against a file you uploaded yourself, so its size is your own list rather than a slice of ours. The free plan has no daily cap either — its month is small enough already. What your own plan allows in a day is on the pricing page.

The month is a calendar month

Every allowance is counted against the calendar month in which it was spent, and every allowance resets on the first. Nothing carries over. When a plan changes mid-month the usage already recorded stays recorded and the new limits apply from the moment the plan does, so an upgrade takes effect on what is left of the month rather than on a new one.

What a limit refusal looks like

A refusal tells you how much you asked for, how much is left, what the limit is, how much of it you have used and which month it is talking about — and it ends by saying that nothing was started. That last part is the important one: an export that has already begun is never truncated to fit an allowance, and an append is never run over the part of your file that fits. You get a refusal and an intact allowance, not a partial result you have to reconcile.

A lapsed subscription is a different refusal with a different fix: nothing is spent, and the message says the subscription rather than the allowance is the problem. Your data, your saved lists and your history stay where they are while it is sorted out.

A pace refusal is a third thing again, and it means wait rather than upgrade. The difference matters: a pace refusal clears within the minute, while an allowance refusal will still be there in an hour. Which is which is spelled out on the API keys page for calls and on the reveals page for reveals.

Reading what you have left

The app shows the month's usage against each allowance on the billing screen, and every member of your organization can see it — a refusal that mentions a number is only useful to somebody allowed to go and look at that number. Through the API, one endpoint reports the plan and the month's usage, and the pace and quota headers on every response carry the same figures. The API reference names them.

An unlimited allowance is reported as unlimited rather than as a very large number, and where a limit does not apply, no header is sent for it at all — a header you cannot trust is worse than no header.