# Code Examples

End-to-end examples of the three-step async workflow: create a search via [`POST /v1/searches`](/api-docs/create-search), poll [`GET /v1/searches/{job_id}`](/api-docs/get-search) until complete, then download each [Parquet shard](/api-docs/reimbursement-data-schema) in the `download_urls` array. Pick the language that matches your stack using the tabs below. Each example paces its polling loop to the [recommended 15–30 second cadence](/api-docs/rate-limits#polling-cadence) and handles both `completed` and `failed` terminal states.

![Three-step async API workflow: create search, poll status, download Parquet shards](/async_api_workflow.svg)



```bash
#!/bin/bash
set -e

API_KEY="${KEEPER_API_KEY:?set KEEPER_API_KEY in your environment}"
BASE="https://api.keeperhealth.com"

# 1. Create the search job
JOB_ID=$(curl -s -X POST "$BASE/v1/searches" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "npis": [1144218512],
    "billing_codes": ["99213", "99214"],
    "fee_schedules": [{"payer":"Cigna","plan":"PPO"}]
  }' | jq -r '.job_id')

echo "Job created: $JOB_ID"

# 2. Poll until terminal state (completed or failed).
# 15 attempts × 20 seconds = 5 minute cap, well inside the recommended
# 15-30s polling cadence.
for attempt in $(seq 1 15); do
  STATUS=$(curl -s -H "Authorization: Bearer $API_KEY" \
    "$BASE/v1/searches/$JOB_ID")
  STATE=$(echo "$STATUS" | jq -r '.status')

  echo "Attempt $attempt: $STATE"

  if [ "$STATE" = "completed" ]; then
    # `download_urls` is always an array — iterate every shard.
    i=0
    echo "$STATUS" | jq -r '.download_urls[]' | while read -r url; do
      curl -o "results-$i.parquet" "$url"
      i=$((i + 1))
    done
    echo "Results saved as results-*.parquet"
    exit 0
  elif [ "$STATE" = "failed" ]; then
    REASON=$(echo "$STATUS" | jq -r '.error')
    echo "Job failed: $REASON" >&2
    exit 1
  fi

  sleep 20
done

echo "Timed out waiting for job" >&2
exit 1
```

```python
import os, time, requests

API_KEY = os.environ["KEEPER_API_KEY"]
BASE    = "https://api.keeperhealth.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Create the search
resp = requests.post(
    f"{BASE}/v1/searches",
    headers=HEADERS,
    json={
        "npis": [1144218512],
        "billing_codes": ["99213", "99214"],
        "fee_schedules": [{"payer": "Cigna", "plan": "PPO"}],
    },
)
resp.raise_for_status()
job_id = resp.json()["job_id"]
print(f"Job created: {job_id}")

# 2. Poll for completion. 15 attempts × 20s = 5 minute cap, within the
# recommended 15-30 second polling cadence.
for attempt in range(1, 16):
    status = requests.get(
        f"{BASE}/v1/searches/{job_id}",
        headers=HEADERS,
    ).json()
    print(f"Attempt {attempt}: {status['status']}")

    if status["status"] == "completed":
        break
    if status["status"] == "failed":
        raise RuntimeError(f"Search job failed: {status.get('error')}")

    time.sleep(20)
else:
    raise TimeoutError("Search did not complete within 5 minutes")

# 3. Download every Parquet shard. `download_urls` is always a list — even
# for single-file results — so iterate without assuming length.
for i, url in enumerate(status["download_urls"]):
    shard = requests.get(url)
    with open(f"results-{i:05d}.parquet", "wb") as f:
        f.write(shard.content)
print(f"Saved {len(status['download_urls'])} Parquet shard(s)")

# Load as a single dataset:
#   import pandas as pd
#   df = pd.read_parquet([f"results-{i:05d}.parquet"
#                         for i in range(len(status["download_urls"]))])
```

```javascript
const API_KEY = process.env.KEEPER_API_KEY;
const BASE = "https://api.keeperhealth.com";
const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Create search
const createResp = await fetch(`${BASE}/v1/searches`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    npis: [1144218512],
    billing_codes: ["99213", "99214"],
    fee_schedules: [{ payer: "Cigna", plan: "PPO" }],
  }),
});
const { job_id } = await createResp.json();
console.log(`Job created: ${job_id}`);

// 2. Poll for completion. 15 attempts × 20s = 5 minute cap.
let status;
for (let attempt = 1; attempt <= 15; attempt++) {
  const resp = await fetch(`${BASE}/v1/searches/${job_id}`, { headers });
  status = await resp.json();
  console.log(`Attempt ${attempt}: ${status.status}`);

  if (status.status === "completed") break;
  if (status.status === "failed") {
    throw new Error(`Search failed: ${status.error}`);
  }

  await new Promise((r) => setTimeout(r, 20_000));
}

if (status?.status !== "completed") {
  throw new Error("Search did not complete within 5 minutes");
}

// 3. Download each Parquet shard. `download_urls` is always an array;
// iterate without assuming length.
const fs = require("fs").promises;
for (let i = 0; i < status.download_urls.length; i++) {
  const shard = await fetch(status.download_urls[i]);
  const buf = Buffer.from(await shard.arrayBuffer());
  await fs.writeFile(`results-${String(i).padStart(5, "0")}.parquet`, buf);
}
console.log(`Saved ${status.download_urls.length} Parquet shard(s)`);
```

```typescript
interface CreateResponse { job_id: string }
interface StatusResponse {
  status: "queued" | "processing" | "completed" | "failed";
  download_urls?: string[];
  error?: string;
}

const API_KEY = process.env.KEEPER_API_KEY!;
const BASE = "https://api.keeperhealth.com";
const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Create search
const createResp = await fetch(`${BASE}/v1/searches`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    npis: [1144218512],
    billing_codes: ["99213", "99214"],
    fee_schedules: [{ payer: "Cigna", plan: "PPO" }],
  }),
});
const { job_id } = (await createResp.json()) as CreateResponse;

// 2. Poll for completion. 15 attempts × 20s = 5 minute cap.
let status: StatusResponse | undefined;
for (let attempt = 1; attempt <= 15; attempt++) {
  const resp = await fetch(`${BASE}/v1/searches/${job_id}`, { headers });
  status = (await resp.json()) as StatusResponse;
  console.log(`Attempt ${attempt}: ${status.status}`);

  if (status.status === "completed") break;
  if (status.status === "failed") {
    throw new Error(`Search failed: ${status.error}`);
  }

  await new Promise((r) => setTimeout(r, 20_000));
}

if (status?.status !== "completed" || !status.download_urls?.length) {
  throw new Error("Search did not complete within 5 minutes");
}

// 3. Download each Parquet shard. `download_urls` is always an array;
// iterate without assuming length.
const fs = (await import("fs")).promises;
for (let i = 0; i < status.download_urls.length; i++) {
  const shard = await fetch(status.download_urls[i]);
  const buf = Buffer.from(await shard.arrayBuffer());
  await fs.writeFile(`results-${String(i).padStart(5, "0")}.parquet`, buf);
}
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

const base = "https://api.keeperhealth.com"

type createResponse struct {
	JobID string `json:"job_id"`
}

type statusResponse struct {
	Status       string   `json:"status"`
	DownloadURLs []string `json:"download_urls"`
	Error        string   `json:"error,omitempty"`
}

func main() {
	apiKey := os.Getenv("KEEPER_API_KEY")
	client := &http.Client{Timeout: 30 * time.Second}

	// 1. Create search
	body, _ := json.Marshal(map[string]any{
		"npis":          []int{1144218512},
		"billing_codes": []string{"99213", "99214"},
		"fee_schedules": []map[string]string{{"payer": "Cigna", "plan": "PPO"}},
	})
	req, _ := http.NewRequest("POST", base+"/v1/searches", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var created createResponse
	json.NewDecoder(resp.Body).Decode(&created)
	fmt.Println("Job created:", created.JobID)

	// 2. Poll for completion. 15 attempts × 20s = 5 minute cap.
	var status statusResponse
	for attempt := 1; attempt <= 15; attempt++ {
		sreq, _ := http.NewRequest("GET", base+"/v1/searches/"+created.JobID, nil)
		sreq.Header.Set("Authorization", "Bearer "+apiKey)
		sresp, err := client.Do(sreq)
		if err != nil {
			panic(err)
		}
		json.NewDecoder(sresp.Body).Decode(&status)
		sresp.Body.Close()
		fmt.Printf("Attempt %d: %s\n", attempt, status.Status)

		if status.Status == "completed" {
			break
		}
		if status.Status == "failed" {
			panic(fmt.Sprintf("search failed: %s", status.Error))
		}
		time.Sleep(20 * time.Second)
	}

	if status.Status != "completed" {
		panic("search did not complete within 5 minutes")
	}

	// 3. Download each Parquet shard. `download_urls` is always an array;
	// iterate without assuming length.
	for i, url := range status.DownloadURLs {
		dl, err := http.Get(url)
		if err != nil {
			panic(err)
		}
		out, _ := os.Create(fmt.Sprintf("results-%05d.parquet", i))
		io.Copy(out, dl.Body)
		out.Close()
		dl.Body.Close()
	}
	fmt.Printf("Saved %d Parquet shard(s)\n", len(status.DownloadURLs))
}
```



## See also

- [Create Search](/api-docs/create-search) — field reference, hard per-request limits, and `Idempotency-Key` header
- [Get Search Status](/api-docs/get-search) — full job state machine, terminal states, and response shapes
- [Reimbursement Data Schema](/api-docs/reimbursement-data-schema) — columns in each downloaded shard
- [Rate Limits](/api-docs/rate-limits) — polling cadence and `Retry-After` handling
- [Errors](/api-docs/errors) — error envelope and retry-safe taxonomy
- [Authentication](/api-docs/authentication) — how to set `KEEPER_API_KEY` and rotate it safely

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

Code Examples

Agentic Prompt

Rate Limits

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 URLs returned by the status endpoint All responses are JSON; results are delivered as one or more Snappy compressed Parquet files (large result sets are sharded, since each shard is capped at 1 GB). See the Reimbursement Data 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 each URL in the pre signed array to retrieve your Parquet shards. 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. Each step below is shown on its own so you can copy, run, and inspect the response before moving on. For a full end to end client with retries and error handling, see Code Examples. 1. Create Search — 2. Poll Status — 3. Download Parquet shards — each URL in Set in your environment before running the snippets below. Not sure what to pass for and ? Use List Payers and List Plans to enumerate the exact strings the API accepts. The values are matched exactly — a typo silently returns zero rows. 1. Submit a search Returns a and . Save the — you'll use it in step 2. <! tabs:start <! tabs:end 2. Check status Call this every 15–30 seconds until is or — see polling cadence. When complete, the response includes a array. <! tabs:start <! tabs:end 3. Download each Parquet shard is always an array — iterate it even for single file results. The URLs are pre signed; do not attach the header. <! tabs:start <! tabs:end Once you've downloaded the Parquet shards, load them as a single dataset with pandas ( ), DuckDB, pyarrow, or any reader that accepts a list of files. See the Reimbursement Data Schema for column definitions. See also List Payers / List Plans — discover valid and strings before building your first request 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 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

API Pricing Keeper Health publishes flat, predictable pricing for programmatic access to healthcare price transparency data. Other vendors in this category typically require a sales engagement to obtain a quote and contract at six or seven figure annual rates. Our pricing is listed below in full. Plan Component Price Annual API subscription $12,000 / year Per result usage fee $5 per (billed entity × payer) There are no per seat fees, per request fees, premium tiers, or payer surcharges. The same rate applies regardless of which payers, plans, or specialties you query. What counts as a billed entity A billed entity is a tax paying organization identified by its EIN (Employer Identification Number, also referred to as a Tax ID or TIN). A single billed entity frequently covers many providers — for example, a hospital system may employ hundreds of physicians who all bill under the same EIN. Usage is charged once per (billed entity, payer) pair , regardless of how many of the following are included in the query: NPIs that roll up to that EIN Billing codes (CPT / HCPCS) Plans within the payer (PPO, HMO, Choice Plus, etc.) Modifiers, fee schedules, or service groups Worked example A search is submitted for 50 NPIs, 20 billing codes, and 3 fee schedules across 2 payers (Cigna and UnitedHealthcare). The 50 NPIs map to 12 distinct EINs in the result set. Distinct billed entities returned: 12 Payers in the request: 2 Billable combinations: 12 × 2 = 24 Usage charge: 24 × $5 = $120 The charge reflects the 24 (billed entity, payer) combinations actually returned by the search — not the 50 NPIs submitted, and not the 60 (NPI × code) combinations queried. If a payer has no contracted rate for a given EIN, that combination is not billed. Why pricing is published Programmatic access to negotiated rate data — the data that hospitals and insurers are required to publish under the Transparency in Coverage rule — is, in our view, more useful to the market when its pricing is public. Keeper Health publishes its rates so that organizations can evaluate, budget for, and procure this data without a multi week sales process. The API is intended for organizations including: Provider groups evaluating payer contracts Self insured employers auditing carrier network rates Academic and policy researchers studying price variation Health technology companies building on top of negotiated rate data Journalists and analysts investigating healthcare pricing A reduced rate is available for academic and nonprofit research. Please contact us for details. How billing works The annual subscription is invoiced up front and grants an API key valid for 12 months. Usage fees are metered against the (billed entity, payer) pairs returned by completed searches and invoiced monthly in arrears. Idempotent retries carrying the same are not double billed. See Create Search. Failed jobs are not billed. Charges accrue only against successfully delivered results. Catalog endpoints — List Payers and List Plans — are not metered. Each billed entity returned by a search is recorded against the organization's monthly usage and is available for review in the account dashboard. How we compare Vendor Annual API access Per record fee Pricing public? Keeper Health $12,000 $5 / (entity × payer) Yes Typical TiC data vendor $150,000 – $1,000,000+ Custom / undisclosed No Direct from payer ingestion $0 license; substantial engineering investment to ingest N/A N/A We are not currently aware of another vendor in the healthcare price transparency space publishing a flat, per result rate at this level. If you have identified one, we would welcome the reference. Frequently asked questions Does the annual fee include usage credits? No. The $12,000 annual fee covers API access, support, and the infrastructure required to keep the underlying data current. Usage is metered separately so that lighter users do not subsidize heavier users. Are volume discounts available? Yes. Organizations consistently pulling more than 100 (entity × payer) combinations per month are eligible for custom pricing. Please contact us to discuss. What is the minimum commitment? The minimum term is 12 months. Trial keys with a limited usage cap may be issued for evaluation purposes; please contact . Are NPIs or billing codes billed individually? No. Any number of NPIs and billing codes may be included within a single (billed entity, payer) pair without additional charge. How can monthly usage be estimated in advance? Run a representative sample search for the providers and payers of interest, count the distinct EINs in the result, and multiply by the number of payers in the request to obtain the per search billable count. Multiply by the expected search frequency to obtain a monthly estimate. Get started Quickstart — submit a first search in approximately five minutes Authentication — how API keys are issued and used Reimbursement Data Schema — column definitions for returned results For pricing, contract, or trial access inquiries, please contact .

Transparent, flat-rate pricing for the Keeper Health API — $12,000 annually plus $5 per billed-entity and payer combination. Public, predictable pricing for healthcare price transparency data.

API Pricing

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. , , ). Enumerate valid values with List Payers. Plan type (e.g. , , ). Enumerate valid values for a given payer with List Plans. Don't hardcode payer and plan names. Values are matched exactly — won't match , and a mistyped plan silently returns zero rows. Pull the authoritative list from List Payers and List Plans and drop the strings straight into . 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 List Payers / List Plans — discover the exact and strings to use in 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 array of pre signed URLs — one per Parquet shard. See the Reimbursement Data 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 (URLs) List of pre signed URLs, one per Parquet shard. Always an array — length is 1 or more, even for single file results. No authentication header is required on the downloads themselves. Only present when is . (ISO 8601) Shared expiration time for every URL in ( 1 hour after they were minted). Re poll the status endpoint to obtain a fresh set after expiry. (ISO 8601) Timestamp when job processing finished. Only present when is . Why multiple URLs? BigQuery shards large result sets into multiple Parquet files on export (each shard is capped at 1 GB). Every file has the same schema; together they are the complete result. Always iterate — do not assume a length. Readers like DuckDB, pandas ( ), and pyarrow accept a list of Parquet files as a single dataset. Download URLs expire. The pre signed URLs are valid for approximately 1 hour and all share the same . If the links have expired, simply poll the status endpoint again to receive a fresh set. 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 Reimbursement Data Schema — columns you'll find in each downloaded shard 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

List every payer available for on Create Search. The field is the exact string to pass back in a search request — use this endpoint to populate a dropdown or validate input rather than hardcoding a list. Example request: GET /v1/payers requests have no body — pass the API key in the header. Headers Header Required Value Yes — see Authentication Response Field Type Description The exact value to pass as on Create Search. Dataset identifier. Pass to List Plans to enumerate plans for a pair. Not used by Create Search. The same may appear more than once. A single dataset can host multiple payer brands (e.g. hosts both and ). Treat the pair as the unit of identity. Results change infrequently and are safe to cache on the client for at least an hour. 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. Contact support. See also List Plans — enumerate plan names for a given payer Create Search — pass the returned values in

List every payer available for fee_schedules[].payer on Create Search.

List Payers

List every plan name available for a given pair. The returned values are the exact strings to pass as on Create Search. Obtain and from List Payers. Example request: GET /v1/payers/{payer key}/plans URL encode the query parameter when it contains spaces or special characters. Headers Header Required Value Yes — see Authentication Path Parameters Parameter Type Description A value from List Payers. Query Parameters Parameter Required Description Yes The string from List Payers. Required because one may host multiple payer brands, and a is only valid against its own payer. Response Field Type Description The exact value to pass as on Create Search. The returned values can be dropped straight into a search: Error responses All error responses use the standard error envelope. HTTP Meaning The query parameter is missing or empty. Missing, malformed, or invalid API key. See Authentication. API key revoked or organization inactive. See Authentication. does not exist, or the pair yielded no plans. These cases are intentionally indistinguishable. Contact support. See also List Payers — enumerate available pairs Create Search — pass the returned values in

List every plan name available for a given payer, ready to drop into fee_schedules[].plan on Create Search.

List Plans for Payer

Reimbursement Data Schema Each row represents a single negotiated rate for a provider–code–plan combination. Rows are deduplicated by EIN — each tuple appears once. 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. Provider's individual name as registered with the NPI. Employer Identification Number of the billing entity. Provider's registered legal business or practice name. Payer network name. May be empty if not specified in the source file. Payer name matching the you passed in on Create Search. Payer plan identifier (slug format, e.g. ). CPT / HCPCS billing code. Category for the billing code (e.g. , ). Service classification — or . CPT modifier codes, if applicable. May be empty. Negotiated rate amount in USD. Medicare reference rate for the same code, when available. as a percentage. Rate type — e.g. , , , . Fee schedule name used for this rate. Grouping category for the service. Delivery format Results are delivered as one or more Snappy compressed Parquet files ( ) downloaded from the pre signed URLs in the array returned by Get Search Status once a job reaches . Every shard has the same schema; together they are the complete result set. BigQuery shards large result sets at export time (the per file cap is 1 GB), so small results typically produce a single file while larger ones produce many. Clients should always iterate rather than assume a length — DuckDB, pandas ( ), and pyarrow all accept a list of Parquet files as a single dataset. Loading tips Files are Snappy compressed Parquet — most modern readers (pandas, DuckDB, pyarrow, Polars, Spark) handle Snappy transparently with no extra flags. Pass the full list of shard paths to your reader to load the result as a single dataset: , , . 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 iterates and writes the shards end to end. See also Get Search Status — returns the these files are fetched from Code Examples — streaming download snippets in four languages Create Search — the request fields ( , , ) that shape what ends up in the Parquet

Column definitions for the reimbursement data returned by the Keeper Health API as Snappy-compressed Parquet shards.

Reimbursement Data 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.

Errors

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

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

Code Examples End to end examples of the three step async workflow: create a search via , poll until complete, then download each Parquet shard in the array. 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 Reimbursement Data Schema — columns in each downloaded shard Rate Limits — polling cadence and handling Errors — error envelope and retry safe taxonomy Authentication — how to set and rotate it safely

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 https://api.keeperhealth.com/v1/payers \ H "Authorization: Bearer $KEEPER API KEY" curl s get data urlencode "payer=Cigna" \ https://api.keeperhealth.com/v1/payers/cigna/plans \ H "Authorization: Bearer $KEEPER API KEY" 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", "download urls": [ "https://storage.googleapis.com/...&X Goog Signature=...", "https://storage.googleapis.com/...&X Goog Signature=..." ], "expires at": "2026 04 11T10:41:02Z" } bash i=0 jq r '.download urls[]' status.json while read r url; do curl o "results $i.parquet" "$url" i=$((i + 1)) done 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.