Do I need an API key?

Yes, for every request. There is no unauthenticated endpoint. Keys are issued on signup — a free trial key needs no card, and paid plans issue keys the same way.

What counts as a request?

One HTTP call to one endpoint. Pagination counts per page. A 4xx caused by a malformed request still counts; a 5xx caused by us does not.

How do I handle rate limits properly?

Read X-RateLimit-Remaining on successful responses and slow down before you are cut off. On a 429, back off exponentially with jitter — retrying immediately spends quota on a response you already know.

Can I see the data before signing up?

Yes, in the Explorer on the dataset page. It runs in your browser against real records, so you can judge whether the data suits you before generating a key.

Not yet. The REST API is the only supported interface today, and it is a handful of lines in any HTTP client. Planned libraries are listed below and are not published.

How will breaking changes be handled?

The path carries the version. /v1 will not change shape underneath you: new fields may be added, existing fields will not be removed or retyped. Error types are part of the contract and change only with a version bump.

One request. Real data.

63,518 records · 49 states and DC · key required

No sales call, no data-use agreement, no CSV download. Sign up, generate a key, and one request queries every OPPS hospital in the country.

Start here

Three steps, then you are querying

Every request carries a key, so the first step is generating one. It takes a minute and the trial needs no card.

Request

curl

curl "https://api.vemon.io/v1/healthcare/prices?procedure=5372&limit=3" \
  -H "Authorization: Bearer vm_live_…"

What comes back

200 OK

{
  "summary": {
    "facilities": 848,
    "median_charge": 3137,
    "spread": 198.9
  },
  "data": [ … 848 facilities, cheapest first ],
  "source": { "data_year": 2024 }
}

In your language

The whole integration

There is no SDK to install and no client to configure. It is an HTTP GET with one header.

python

import requests

r = requests.get(
    "https://api.vemon.io/v1/healthcare/prices",
    params={"procedure": "5372"},
    headers={"Authorization": "Bearer vm_live_…"},
    timeout=10,
)
r.raise_for_status()
print(r.json()["summary"]["median_charge"])

javascript

const res = await fetch(
  "https://api.vemon.io/v1/healthcare/prices?procedure=5372",
  { headers: { Authorization: `Bearer ${key}` } },
);
if (!res.ok) throw new Error(res.statusText);
const { summary } = await res.json();
console.log(summary.median_charge);

req, _ := http.NewRequest("GET",
  "https://api.vemon.io/v1/healthcare/prices?procedure=5372", nil)
req.Header.Set("Authorization", "Bearer "+key)

res, err := http.DefaultClient.Do(req)
if err != nil { return err }
defer res.Body.Close()

var out Response
json.NewDecoder(res.Body).Decode(&out)

Recipes

Four things people do first

Substitute your key and each of these runs as written.

Find a facility when you only know its name

Resolve a hospital name to the CCN your price queries need.

curl

curl "https://api.vemon.io/v1/search?q=tampa&type=facility&limit=5" \
  -H "Authorization: Bearer vm_live_…"

Compare one procedure across a state

Narrow to a jurisdiction and read the summary for the whole match, not the page.

curl

curl "https://api.vemon.io/v1/healthcare/prices?procedure=5372&state=CA&limit=10" \
  -H "Authorization: Bearer vm_live_…"

Find the procedures with the widest variation

Sort by spread to see where the charge field carries the least information.

curl

curl "https://api.vemon.io/v1/healthcare/procedures?sort=spread&min_facilities=200&limit=10" \
  -H "Authorization: Bearer vm_live_…"

Discover what is loaded before hardcoding an id

Ask the catalog rather than assuming. It reports coverage gaps too.

curl

curl "https://api.vemon.io/v1/datasets" \
  -H "Authorization: Bearer vm_live_…"

Limits

Rate limits and how to respect them

Two ceilings: a burst rate per second and a volume quota per month. Both are visible on every response.

Plan	Burst	Monthly
Free	10/s	10,000
Developer	50/s	1,000,000
Startup	200/s	10,000,000
Business	500/s	50,000,000
Enterprise	custom	custom

At your monthly ceiling the API returns 429 and stops. You are never billed for an overage you did not agree to — warnings go out at 80%, 90%, and 100%.

Back off properly

python

for attempt in range(5):
    r = session.get(url, headers=headers)
    if r.status_code != 429:
        break
    # exponential, with jitter so clients do not
    # synchronise and retry in lockstep
    wait = min(2 ** attempt, 30) + random.random()
    time.sleep(wait)

Every response carries X-RateLimit-Remaining and X-RateLimit-Reset, including successful ones, so you can slow down before you are stopped rather than after.

Errors

Fail loudly, branch on type

Every failure carries a stable machine-readable type and a message worth logging.

400 Bad Request

{
  "error": {
    "type": "invalid_parameter",
    "message": "Unknown parameter: stat. Supported: procedure, state, limit."
  }
}

Branch on type, never on message. Messages are written for humans and will be reworded; types are part of the contract.

Unknown parameters are rejected
A typo returns 400 rather than being ignored. Silently dropping it would hand you plausible but wrong rows.
429 and 500 are worth retrying
Transient. Back off and the same request will likely succeed.
400 and 401 are not
The request or the key is wrong. Retrying burns quota and changes nothing.
404 means no data for those arguments
The endpoint is valid. Retry only if you expect the data to land later.

Stability

What will and will not change

An integration is a promise. These are the terms of it.

Additive only within /v1

New fields may appear. Existing fields will not be removed or retyped.

Error types are frozen

A type will not change meaning without a version bump. Message text may be reworded.

Data versions are addressable

When a dataset refreshes, the prior version stays queryable so a published result reproduces.

SDKs

Planned, not published

None of these exist yet. Until they do, the REST API is the only supported interface — and it is stable and documented.

Python

Soon

pip install vemon3.10+

TypeScript

Soon

npm i @vemon/sdkNode 20+

Go

Soon

go get vemon.io/go1.22+

CLI

Soon

brew install vemonmacOS, Linux

Questions

Asked most often

Do I need an API key?: Yes, for every request. There is no unauthenticated endpoint. Keys are issued on signup — a free trial key needs no card, and paid plans issue keys the same way.
What counts as a request?: One HTTP call to one endpoint. Pagination counts per page. A 4xx caused by a malformed request still counts; a 5xx caused by us does not.
How do I handle rate limits properly?: Read X-RateLimit-Remaining on successful responses and slow down before you are cut off. On a 429, back off exponentially with jitter — retrying immediately spends quota on a response you already know.
Can I see the data before signing up?: Yes, in the Explorer on the dataset page. It runs in your browser against real records, so you can judge whether the data suits you before generating a key.
Is there an SDK?: Not yet. The REST API is the only supported interface today, and it is a handful of lines in any HTTP client. Planned libraries are listed below and are not published.
How will breaking changes be handled?: The path carries the version. /v1 will not change shape underneath you: new fields may be added, existing fields will not be removed or retyped. Error types are part of the contract and change only with a version bump.

Something not covered here? support@vemon.io reaches a person.

Query 2024 charge data in one request.

Generate a trial key in a minute. 10,000 requests a month, no card.

Read the docs Open the Explorer