---
title: "Several rate queries in one call"
method: POST
path: "/v1/rates/batch"
tags: ["rates"]
---

# Several rate queries in one call

`POST /v1/rates/batch`

## Request

- Base URL: `https://api.ticexplorer.com`
- URL: `https://api.ticexplorer.com/v1/rates/batch`
- Auth: HTTP bearer

Up to 10 `get_rates` requests (different coverages, areas, entities or code sets) in one call.

**Workflows**

Workflow `compare-coverage-routes`, step 2/2 `rates-by-route`: Compare the same services under the person's plan, Original Medicare and hospital cash prices in one call.
- Purpose: One request per coverage route (plan, medicare, hospital cash), each with a label.
- Call after: `find_codes`

## Request body

- RatesBatchRequest
  - `requests` RatesRequest[], required
    - `coverage` Coverage, required
      - `type` 'plan' | 'medicare' | 'hospital': plan = a plan from find_plan (insurer rate files); medicare = Original Medicare fee schedule; hospital = hospitals' own price files (Medicare Advantage, Medicaid, cash/self-pay): each hospital's posted rate per payer/plan as the hospital wrote it (not necessarily the person's plan), mostly facility charges; cash = its discounted cash price, not the gross charge. price_claim does not accept hospital.
      - `plan_id` string, nullable: Required when type = plan; from find_plan.
      - `hospital_coverage` string, nullable: For type = hospital: medicare_advantage | medicaid | cash | a payer name.
    - `codes` string[], required: Billing codes from find_codes (CPT/HCPCS, or an APC number for hospital case rates).
    - `providers` Providers
      - `tins` string[]: Billing entity tax IDs (from find_providers), e.g. 84-1179794.
      - `npis` string[]: NPIs of locations or clinicians.
      - `names` string[]: Substring match on billing entity / location names.
    - `area` Area, required
      - `zip` string, required: 5-digit ZIP the person is near.
      - `miles` number: Search radius in miles.
    - `limit` integer
    - `cursor` integer: Pagination cursor from next_cursor.
    - `wait_seconds` integer: How long to wait for rate files being indexed for the first time.
    - `label` string, nullable: Echoed back in batch results.

## Response `200`

Successful Response

- RatesBatchResult
  - `data` RatesBatchItem[], required
    - `index` integer, required
    - `label` string, nullable
    - `ok` boolean, required
    - `data` RateRow[], nullable
      - `code` string, required
      - `code_type` string, required
      - `billing_entity` object, required: {tin, name, is_hospital}: prices belong to billing entities.
      - `location` object, required
      - `price` Price, required
        - `kind` string, required: negotiated | fee_schedule | derived | per_diem | percent_of_charges | placeholder | algorithm ...
        - `amount` number, nullable: Allowed dollars per unit; null when not a dollar price.
        - `percent` number, nullable
        - `unit` string, required: per_service | per_day | per_apc_case | percent_of_billed_charges | none
        - `is_dollar_price` boolean, required
      - `billing` Billing, required
        - `billing_class` string, nullable: professional (clinician claim) | institutional (facility claim)
        - `setting` string, nullable
        - `modifiers` string[]
        - `component` string, required: global | professional_component | technical_component | professional | facility | drug
        - `applies_when` string, required
        - `place_of_service` string, required: non_facility | facility | mixed | unspecified
      - `hospital_outpatient` object, nullable: APC, status indicator, packaging (institutional rows).
      - `benchmark` object, nullable: Medicare amount for the same service/setting + percent_of_medicare.
      - `flags` string[]
      - `quality` object, nullable: {score 1-5, reason}: 5 corroborated by the hospital's own file, 4 consistent with Medicare band, 3 unchecked / not corroborated, 2 unusual, 1 not a usable dollar price (guide://fields).
      - `hospital_file_rate` object, nullable: Hospital rows: the same hospital's own price file for this payer and code (amount, plan_as_written, agreement, difference_percent).
      - `evidence` object, required
      - `provenance` object, required: payer, plan, files, insurer_date_label vs retrieved_at, future_dated_label.
    - `error` ErrorBody
      - `code` string, required: Stable machine-readable error code, e.g. plan_not_found, invalid_zip, unauthorized.
      - `message` string, required
      - `hint` string
  - `next_cursor` integer, nullable
  - `next_steps` string[]

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests

---

[API](https://skmtc.dev/ticexplorer/apis/tic-explorer-api.md) · [All operations](https://skmtc.dev/ticexplorer/apis/tic-explorer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ticexplorer/apis/tic-explorer-api/revisions/9800d20135b9?raw)