
# Rate Limits

The Keeper Health API enforces limits at three levels: **per request** (hard input caps), **per second** (rate limiting), and **per account** (quota and concurrency). Staying under them is simple — honor `Retry-After` when you see a `429` or `503` and don't poll more aggressively than the recommended cadence.

## Default limits

Default limits are listed below. Contact [company@keeperhealth.com](mailto:company@keeperhealth.com) to discuss a higher tier for your account.

| Limit | Default |
| --- | --- |
| Requests per second | 5 |
| Concurrent in-flight jobs | 10 |
| NPIs per request | 1000 (hard limit) |
| Billing codes per request | 100 (hard limit) |
| Fee schedules per request | 20 (hard limit) |
| Download URL validity | ~1 hour |
| Job result retention | 30 days |

Requests that exceed the **per-request** hard limits are rejected with `400 validation_error` before any work is enqueued — see [Create Search → Request Body](/api-docs/create-search#request-body) for field limits and [Errors](/api-docs/errors) for the envelope shape.

Requests that exceed the **per-second** rate limit receive `429 rate_limited` with a `Retry-After` header — see [Errors](/api-docs/errors) for the response body.

## Polling cadence

> **Recommended:** poll every **15–30 seconds**. More frequent polling does not speed up your job and is the most common reason customers hit the rate limiter. [Code Examples](/api-docs/code-examples) shows correctly-paced polling loops in cURL, Python, JavaScript, TypeScript, and Go.

- Typical completion time for small requests (≤ 10 NPIs, 1 fee schedule) is **30–60 seconds**.
- Larger requests scale proportionally with the number of NPIs, billing codes, and fee schedules.
- If you see `status: "processing"` for more than **5 minutes**, something is likely wrong — contact [company@keeperhealth.com](mailto:company@keeperhealth.com) with your `job_id`. See [Get Search Status](/api-docs/get-search#status-values) for the full state machine.
- There is **no webhook** in v1. Polling is the only notification mechanism.

## Handling `429` and `503`

Both `429 rate_limited` and `503` responses (`enqueue_failed`, `service_unavailable`) include a `Retry-After` header with the number of seconds to wait before retrying. Honor it — don't invent your own schedule.

```bash
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}
```

If you don't see a `Retry-After` header (e.g. on a transient network failure), fall back to exponential backoff:

```
attempt 1: wait 5s
attempt 2: wait 10s
attempt 3: wait 20s
attempt 4: wait 40s
```

Use an [`Idempotency-Key`](/api-docs/create-search#idempotency) on the retried `POST /v1/searches` so you don't accidentally create duplicate jobs when a retry races with a slow-but-successful original request.

If you consistently hit rate limits after honoring `Retry-After`, contact [company@keeperhealth.com](mailto:company@keeperhealth.com) to discuss a higher tier.

## See also

- [Create Search](/api-docs/create-search) — per-request limits enforced at the field level
- [Get Search Status](/api-docs/get-search) — what you're polling, and when to stop
- [Code Examples](/api-docs/code-examples) — polling loops paced to these limits
- [Errors](/api-docs/errors) — response envelope for `429` and `503`


Request-rate, per-request, and quota limits for the Keeper Health API, plus recommended polling cadence.

Rate Limits

Code Examples

Errors

Keeper Health API The Keeper Health API is designed for our partnering healthcare organizations and researchers with some technical experience that would prefer simple access to reimbursement rates without a user interface, and would like to see the full negotiated rates / allowed amounts for many providers at once. Overview Organizations use our API to access negotiated rates for preprocessed and up to date payer contracts, between BUCA payers and providers. Search by provider NPI, billing code, and health plan to see federally mandated payer reported data of what healthcare providers are reimbursed. The API follows a three step asynchronous pattern: 1. Submit a search — 2. Poll for completion — 3. Download results — the pre signed URL returned by the status endpoint All responses are JSON; results are delivered as gzip compressed CSV files (see the CSV Output Schema for column definitions). Every non 2xx response follows the standard error envelope. Quick Start Get from zero to your first successful request in a few minutes. 1. Register for an account The Keeper Health API is a paid product. To request access, email company@keeperhealth.com with a short description of your use case and expected request volume. Our team will set up your account and respond with next steps. 2. Get your API key After your account is provisioned, our team will email you a developer API key directly. Treat this key like a password — store it in a secrets manager or environment variable, and never commit it to source control. See Authentication for header format, rotation, and security best practices. To rotate or replace a key, email company@keeperhealth.com. 3. Make your first request Copy and paste the snippet below to submit a search for a single provider and billing code. This is the "Hello World" of the Keeper Health API — pick your language with the tabs. <! tabs:start <! tabs:end You'll receive a in the response. Poll until is , then download the pre signed to retrieve your CSV. See the Quickstart for the full three step workflow, or Code Examples for complete end to end clients in four languages. Pricing & Quotas Pricing is based on search volume and is tailored to each customer's use case. There is a fixed cost for API access with associated quota. — email company@keeperhealth.com for a quote. If your workload requires higher limits than your current plan allows, contact company@keeperhealth.com to discuss a quota adjustment. Rate limits. API requests are rate limited per API key. If you exceed the limit, the API returns a status code. Implement exponential backoff in your polling logic to stay within limits. See Rate Limits for numeric limits, recommended polling cadence, and backoff guidance.

Search negotiated rates from insurance machine-readable files by provider NPI, billing code, and fee schedule.

Overview

Quickstart The API follows a three step asynchronous pattern: submit a search, poll for completion, then download results. This page is the shortest possible walkthrough — for a full working client in four languages, see Code Examples. 1. Create Search — 2. Poll Status — 3. Download CSV — Set in your environment before running the snippets below. Full workflow <! tabs:start <! tabs:end Once you've downloaded the CSV, you can load it into any analytics tool or pipeline. See the CSV Output Schema for column definitions. See also Create Search — full request body, headers, and support Get Search Status — job state machine and terminal states Code Examples — complete polling loops with error handling in cURL, Python, JavaScript/TypeScript, and Go Rate Limits — recommended polling cadence (15–30 seconds) Errors — how to read error responses and what's retry safe

Submit a search, poll for completion, and download results in three steps.

Quickstart

Authentication All requests require a Bearer token in the header. API keys are prefixed with . Every endpoint in the API — Create Search and Get Search Status — accepts this header. Keep keys secret. Never expose API keys in client side code, public repositories, or browser requests. Use environment variables or a secrets manager. Request a Key The Keeper Health API is a paid product. To request a developer API key, email company@keeperhealth.com with: A short description of your use case Your expected request volume (searches per day or month) The organization the key will be billed to Our team will provision an account and email you a key directly. Store it in a secrets manager or environment variable — never commit it to source control. Rotate a Key If you believe an API key has been leaked, exposed in a public repository, or committed to source control, rotate it immediately. 1. Email company@keeperhealth.com from the address associated with your account. 2. Include the first 8 characters of the compromised key (e.g. ) — never send the full key. 3. Briefly describe how the leak occurred so we can confirm the scope of the rotation. We will issue a new key and revoke the compromised one. Revocation is immediate: any request made with the old key after rotation will return with (see the full error envelope). Update your environment variables and redeploy before the old key is revoked to avoid downtime. Prevention. Use a secrets manager (AWS Secrets Manager, Google Secret Manager, HashiCorp Vault, Doppler, etc.) rather than committing keys to files. Add to and scan your repository history with tools like before pushing. Security Best Practices 1. Store your API key in a secret manager , not in source control. Use environment variables or your platform's secret store. 2. Use a different key per environment (dev, staging, prod). If one leaks, you only have to rotate one. 3. Use descriptive names when requesting keys. If you need multiple keys, each one should identify its purpose (e.g. vs ). 4. Rotate on personnel changes. If an engineer leaves, ask us to revoke keys they had access to. 5. Never share signed s in tickets, chat logs, or public repos. They expire in an hour but can expose data in the meantime. 6. Monitor for and responses. These indicate an auth problem that should trigger an alert in your system. Help The API distinguishes between two authentication failure modes. Both follow the standard error envelope: — the header is missing, malformed, or the key value is not recognized. Fix the header or the key value. — the key is syntactically valid but has been revoked or the organization is inactive . Request a new key; do not retry. If your request returns , check that: The header is formatted exactly as (note the space after ) The key value matches what was emailed to you, with no leading or trailing whitespace You are hitting and not a staging URL If your request returns , the key itself is no longer active. Email company@keeperhealth.com to request a new key. For anything else — onboarding, billing, quota adjustments, or integration questions — reach out to company@keeperhealth.com and our team will respond within one business day. See also Quickstart — your first request end to end Create Search — the endpoint every key is used on Errors — the full error envelope and type taxonomy Rate Limits — per key quotas and handling

Authenticate API requests with a Bearer token in the Authorization header.

Authentication

Submit an asynchronous search job to query negotiated rates across payer machine readable files. Returns immediately with a you can pass to Get Search Status to poll for completion. You can make a request for a single Payer and Plan combination (canonically called a fee schedule), or multiple fee schedules at once. Example request for multiple fee schedules: POST /v1/searches Headers Header Required Value Yes — see Authentication Yes Strongly recommended A client chosen string, up to 255 printable ASCII characters. Repeat POSTs with the same key within 24 hours return the original instead of creating a duplicate billable job. See Idempotency. Request Body Field Type Required Description Yes One or more 10 digit National Provider Identifier numbers. Up to 1000 per request. Yes CPT or HCPCS billing codes to retrieve rates for. Up to 100 per request. Yes Filter results by payer and plan. Up to 20 per request. See fields below. No If , uses development datasets instead of production data. Default . object Field Type Description Payer name (e.g. , , ). Plan type (e.g. , , ). Requests that exceed the hard per request limits (1000 NPIs, 100 billing codes, 20 fee schedules) are rejected with before any work is enqueued. See Rate Limits for the full limit table and Errors for the validation error envelope shape. Response — the job has been queued for processing. The response includes a header with the status polling URL. Field Type Description (UUID) Unique identifier for this search job. Pass it to Get Search Status to poll and retrieve results. Current job state. One of: , , , . New jobs always start in . See the full state machine. (ISO 8601) Timestamp when the job was created. (URL) Convenience URL for polling the job status. Idempotency Strongly recommended. We strongly recommend sending an on every request. Searches are billable, long running jobs — an accidental retry without a key creates a duplicate job, duplicate work, and duplicate cost. Treat the key as mandatory in production code paths. accepts an header. When present, repeat requests from the same organization with the same key within a 24 hour window return the original (still , with an response header) instead of creating a second job. Use this on any retry path that might fire twice — cron jobs over flaky networks, job runners with at least once semantics, UI flows where a user could double click a submit button. Requirements: Up to 255 printable ASCII characters Unique per logical request — reuse the same key for safe retries of the same intended operation, generate a new one for a new intended operation Scoped per organization — two different orgs using the same key are independent Without an , every POST creates a new job, including retries. If your code might retry network failures, store the after the first and re poll instead of re POSTing. Error responses All error responses use the standard error envelope. HTTP Meaning A field failed validation (e.g. empty , over a per request limit). lists each failing field. The request body is missing, not valid JSON, or the header is malformed. Missing, malformed, or invalid API key. See Authentication. API key revoked or organization inactive. See Authentication. Transient — safe to retry. header is set. See Rate Limits. Contact support. See also Get Search Status — poll the job you just created Code Examples — full end to end client in four languages Rate Limits — hard per request limits and quotas Errors — full error envelope taxonomy

Submit an asynchronous search job to query negotiated rates across payer machine-readable files.

Create Search

Retrieve the current status of a search job created via Create Search. Safe to call repeatedly. Once is , the response includes a pre signed for the results file — see the CSV Output Schema for what's inside. Example request: GET /v1/searches/{job id} requests have no body — pass the in the URL path and the API key in the header. The three possible successful response shapes — / , , and — are shown below. HTTP status is always . A successful request to this endpoint always returns HTTP , regardless of whether the job itself is , , , or . The HTTP code reflects "the status check succeeded" — the job's actual state lives in the response body's field. Read it, not the HTTP code, to detect job failure. Headers Header Required Value Yes — see Authentication Path Parameters Parameter Type Description (UUIDv4) The job identifier returned from Create Search. Status values Meaning Accepted and waiting for a worker. Usually flips to within seconds. Worker is running the search against BigQuery. Terminal. and are set. Terminal. The field contains a human readable failure reason. and are terminal — once a job reaches either, it will never change state again. Stop polling as soon as you see one. Poll every 15–30 seconds; see Rate Limits for the recommended cadence, and Code Examples for complete polling loops in four languages. Response — queued / processing Response — completed Field Type Description (URL) Pre signed URL to download the gzipped CSV results file. No authentication header is required. Only present when is . (ISO 8601) Expiration time for the download URL ( 1 hour after it was minted). Re poll the status endpoint to obtain a fresh URL after expiry. (ISO 8601) Timestamp when job processing finished. Only present when is . Download URLs expire. The pre signed URL is valid for approximately 1 hour. If the link has expired, simply poll the status endpoint again to receive a fresh one. Do not cache or persist signed URLs — always re fetch them via this endpoint. Response — failed Field Type Description Human readable reason the job failed. Only present when is . Failed jobs are terminal. Read the field, correct the underlying issue, and submit a corrected request as a new job via Create Search. Error responses All error responses use the standard error envelope. HTTP Meaning Missing, malformed, or invalid API key. See Authentication. API key revoked or organization inactive. See Authentication. The does not exist, or belongs to a different organization. These cases are intentionally indistinguishable to avoid confirming the existence of other customers' jobs. Contact support. See also Create Search — submit the job you're polling here CSV Output Schema — columns you'll find in the downloaded file Code Examples — complete polling loops with error handling Rate Limits — polling cadence and handling Errors — full error envelope taxonomy

Retrieve the current status of a search job and obtain a download URL when complete.

Get Search Status

CSV Output Schema Results are delivered as a gzip compressed CSV file ( ) downloaded from the pre signed returned by Get Search Status once a job reaches . Each row represents a single negotiated rate for a provider–code–plan combination. Rows are deduplicated across all selected columns . Each unique combination of provider details (NPI and EIN), network name, plan name, billing code, modifiers, and rate details appears exactly once. Consequently, if the same rate was reported for multiple network names — or if multiple NPIs map to the same EIN — they will appear as separate distinct rows in the final table. Column Type Description 10 digit National Provider Identifier. Employer Identification Number of the billing entity. Payer network name. May be empty if not specified in the source file. Provider's registered legal business or practice name. Payer plan identifier (slug format, e.g. ). CPT / HCPCS billing code. Service classification — or . CPT modifier codes, if applicable. May be empty. Negotiated rate amount in USD. Rate type — e.g. , , , . Fee schedule name used for this rate. Grouping category for the service. Number of distinct rate values observed for the tuple . Useful for flagging codes where the provider has multiple contracted rates under the same plan. Loading tips The file is gzipped — decompress before loading, or use a reader that handles gzip natively (pandas' , DuckDB's , etc.). Every row has an , so you can join results across providers sharing a TIN without additional lookups. Empty strings are used for missing string fields, not . Code Examples show how each language downloads and writes the gzipped file end to end. See also Get Search Status — returns the this file is fetched from Code Examples — streaming download snippets in four languages Create Search — the request fields ( , , ) that shape what ends up in the CSV

Column definitions for the gzip-compressed CSV results file returned by the Keeper Health API.

CSV Output Schema

Errors Every non 2xx response from the Keeper Health API follows the same JSON envelope. Branch your client code on , not on — the type is a stable machine readable slug, while messages may be reworded for clarity over time. See Code Examples for end to end clients that handle these errors. Error envelope Field Type Description string Stable machine readable slug, e.g. . Branch on this. string Short human readable summary. Safe to log and surface. array Optional. Structured field level information. Present on validation errors; omitted otherwise. Error types HTTP Meaning A request field failed validation. lists each failing field. See Create Search and Rate Limits for the hard per request limits. The request body is missing, not valid JSON, or the header is malformed. See Create Search → Idempotency. The API key is missing, malformed, or invalid. See Authentication. The API key has been revoked or the organization is inactive. See Authentication → Help. The does not exist, or belongs to a different organization. See Get Search Status. You've exceeded the rate limit. A header is set. See Rate Limits. The job could not be enqueued. Transient — safe to retry. is set. A backend dependency is temporarily unavailable. Safe to retry. is set. Something broke on our end. Log the response and contact support. The header and responses include a header with the number of seconds to wait before retrying. Honor it rather than inventing your own backoff schedule. See Rate Limits for details. Retry safe vs. not retry safe Safe to retry (ideally with an so you don't create duplicate jobs — see Code Examples for language specific retry loops): / — honor — honor Network errors, connection drops, timeouts Not retry safe — fix the request first: / — the request is malformed. Retrying unchanged produces the same 400. — your key is wrong. Do not retry until fixed. — your key is revoked or your organization is inactive. A note on job failures A job that ends in a terminal failure state ( in the body of a response) still returns HTTP — the status check itself succeeded; the job is just done and didn't succeed. Read the field in the JSON body, not the HTTP status code, to detect terminal job failure. See Get Search Status for details. See also Authentication — resolves and Rate Limits — resolves and explains Create Search — resolves (hard limits and field shapes) Get Search Status — resolves and explains terminal state jobs Code Examples — polling loops with proper error handling

Standard HTTP status codes and the common error envelope returned by every non-2xx response.

Rate Limits The Keeper Health API enforces limits at three levels: per request (hard input caps), per second (rate limiting), and per account (quota and concurrency). Staying under them is simple — honor when you see a or and don't poll more aggressively than the recommended cadence. Default limits Default limits are listed below. Contact company@keeperhealth.com to discuss a higher tier for your account. Limit Default Requests per second 5 Concurrent in flight jobs 10 NPIs per request 1000 (hard limit) Billing codes per request 100 (hard limit) Fee schedules per request 20 (hard limit) Download URL validity 1 hour Job result retention 30 days Requests that exceed the per request hard limits are rejected with before any work is enqueued — see Create Search → Request Body for field limits and Errors for the envelope shape. Requests that exceed the per second rate limit receive with a header — see Errors for the response body. Polling cadence Recommended: poll every 15–30 seconds . More frequent polling does not speed up your job and is the most common reason customers hit the rate limiter. Code Examples shows correctly paced polling loops in cURL, Python, JavaScript, TypeScript, and Go. Typical completion time for small requests (≤ 10 NPIs, 1 fee schedule) is 30–60 seconds . Larger requests scale proportionally with the number of NPIs, billing codes, and fee schedules. If you see for more than 5 minutes , something is likely wrong — contact company@keeperhealth.com with your . See Get Search Status for the full state machine. There is no webhook in v1. Polling is the only notification mechanism. Handling and Both and responses ( , ) include a header with the number of seconds to wait before retrying. Honor it — don't invent your own schedule. If you don't see a header (e.g. on a transient network failure), fall back to exponential backoff: Use an on the retried so you don't accidentally create duplicate jobs when a retry races with a slow but successful original request. If you consistently hit rate limits after honoring , contact company@keeperhealth.com to discuss a higher tier. See also Create Search — per request limits enforced at the field level Get Search Status — what you're polling, and when to stop Code Examples — polling loops paced to these limits Errors — response envelope for and

Code Examples End to end examples of the three step async workflow: create a search via , poll until complete, then download the gzipped CSV. Pick the language that matches your stack using the tabs below. Each example paces its polling loop to the recommended 15–30 second cadence and handles both and terminal states. <! tabs:start <! tabs:end See also Create Search — field reference, hard per request limits, and header Get Search Status — full job state machine, terminal states, and response shapes CSV Output Schema — columns in the downloaded file Rate Limits — polling cadence and handling Errors — error envelope and retry safe taxonomy Authentication — how to set and rotate it safely

Full working examples in cURL, Python, JavaScript/TypeScript, and Go.

Agentic Prompt If you're building with an AI coding agent (Claude Code, Cursor, Windsurf, a custom agent, etc.) and want it to integrate the Keeper API, paste the block below into your agent's system prompt or initial instructions. It is self contained — it covers the full async workflow, authentication, idempotency, polling, error handling, and the shape of the CSV output so the agent can write correct code on the first try without re reading the docs. Keep your API key away from the agent Treat your Keeper API key like a production database password. The goal is that the model never sees the key's value, in any message, tool call, or file it reads . Do not paste the key into the chat. Not in the system prompt, not in a user message, not in a file you show the model. Set the key as an environment variable in the shell / container / CI runner where the agent's code execution tool runs — e.g. in a terminal the model does not have stdout access to, or as a secret in your CI/hosting provider. The agent references the key by name, never by value. Generated code should read / / — the literal string must never appear in code, logs, prompts, or commit history. Do not , , or log the key in any command the agent runs. If you need to check the key is set, check its length ( ), not its value. Do not commit files. Add to before the agent writes any code. Rotate immediately if a key ever appears in a chat transcript, a log, or a commit — assume it is compromised. The prompt below is written so a well behaved agent will naturally follow these rules. Keep it that way: don't edit the prompt to include the key literal "just this once." The prompt bash curl X POST https://api.keeperhealth.com/v1/searches \ H "Authorization: Bearer $KEEPER API KEY" \ H "Content Type: application/json" \ H "Idempotency Key: acme weekly rates 2026 04 14" \ d '{ "npis": [1144218512, 1234567890], "billing codes": ["99213", "99214"], "fee schedules": [ {"payer": "Cigna", "plan": "PPO"}, {"payer": "UnitedHealthcare", "plan": "Choice Plus"} ], "testing": false }' json { "job id": "6f4245de 4b44 4bb6 aaae f11c0d4f45c0", "status": "queued", "created at": "2026 04 11T09:39:35Z", "status url": "https://api.keeperhealth.com/v1/searches/6f4245de 4b44 4bb6 aaae f11c0d4f45c0" } bash curl https://api.keeperhealth.com/v1/searches/6f4245de 4b44 4bb6 aaae f11c0d4f45c0 \ H "Authorization: Bearer $KEEPER API KEY" json { "job id": "6f4245de 4b44 4bb6 aaae f11c0d4f45c0", "status": "processing", "created at": "2026 04 11T09:39:35Z" } json { "job id": "6f4245de 4b44 4bb6 aaae f11c0d4f45c0", "status": "completed", "created at": "2026 04 11T09:39:35Z", "completed at": "2026 04 11T09:41:02Z", "row count": 48213, "download url": "https://storage.keeperhealth.com/results/6f4245de ....csv.gz?X Amz Signature=..." } bash curl o results.csv.gz "<download url from step 2 " gunzip results.csv.gz json { "error": { "type": "validation error", "message": "...", "details": [...] } } KEEPER API KEY .env .gitignore You are integrating... ...call the REST API directly. CLAUDE.md .cursorrules` / equivalent rules file, or the initial message you send the agent. 5. Ask the agent to build the integration in whatever language and framework your project uses — it now has everything it needs, without ever seeing the key's value. If you want a minimal reference implementation to compare the agent's output against, see the Quickstart and Code Examples pages.

A copy-paste system prompt that teaches an AI coding agent how to call the Keeper API correctly end-to-end — without ever seeing your API key.

Limit	Default
Requests per second	5
Concurrent in-flight jobs	10
NPIs per request	1000 (hard limit)
Billing codes per request	100 (hard limit)
Fee schedules per request	20 (hard limit)
Download URL validity	~1 hour
Job result retention	30 days

Rate Limits

Default limits

Polling cadence

Handling 429 and 503

See also

Handling `429` and `503`