---
title: "Batch Lookup Bills"
method: GET
path: "/api/v1/bills/batch"
tags: ["bills"]
---

# Batch Lookup Bills

`GET /api/v1/bills/batch`

## Request

- Base URL: `https://api.billcommons.org`
- URL: `https://api.billcommons.org/api/v1/bills/batch`
- Auth: none declared

Resolve up to 100 bills in one request.

Exists because watchlist monitoring -- the main reason to consume this API
-- was one HTTP round trip per bill. A caller tracking 160 bills spent 160
requests to answer "did anything move?", which is both slow for them and
the single easiest way to walk into the rate limit.

Anything requested but not resolved comes back in `not_found` rather than
being silently absent; see BillBatchEnvelope.

## Query parameters

- `ids` string, nullable: Comma-separated bill UUIDs, e.g. `ids=<uuid>,<uuid>`
- `keys` string, nullable: Comma-separated `JURISDICTION:BILL_NUMBER` pairs, e.g. `keys=HI:SB2135,NY:S9417`. Bill numbers are normalized, so `HI:sb 2135` resolves the same bill. Append a session to disambiguate: `NY:S9417:2025-2026 Regular Session`.

## Response `200`

Successful Response

- BillBatchEnvelope: Response for the batch lookup. `not_found` is the point of the shape. A batch endpoint that just returns the rows it managed to resolve makes a typo, a renumbered bill and a jurisdiction we do not cover all look identical to a caller diffing counts -- and this project has already shipped two bugs where a short result was read as a complete one. Every requested key is accounted for in exactly one of the three fields. `ambiguous` is kept separate from `not_found` because they call for opposite actions. Not-found means the bill is not here; ambiguous means it is here more than once (the same number in several sessions) and the request needs a session to pick one. It maps the key to the session identifiers that matched, so the caller can re-ask without a second query. Folding these together would tell a consumer to drop a bill we hold.
  - `data` BillSummary[], required
    - `id` string, uuid, required
    - `jurisdiction_id` string, uuid, required
    - `session_id` string, uuid, required
    - `jurisdiction_abbreviation` string, nullable
    - `session_identifier` string, nullable
    - `chamber` string, nullable
    - `identifier` string, required
    - `identifier_norm` string, required
    - `title` string, required
    - `short_title` string, nullable
    - `bill_type` string, nullable
    - `status` string, nullable
    - `status_date` string, date, nullable
    - `introduced_date` string, date, nullable
    - `latest_action_text` string, nullable
    - `latest_action_date` string, date, nullable
    - `source_url` string, nullable
    - `updated_at` string, date-time, nullable
  - `not_found` string[], required
  - `ambiguous` object
  - `meta` object, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/billcommons/apis/bill-commons-api.md) · [All operations](https://skmtc.dev/billcommons/apis/bill-commons-api/llms.txt) · [OpenAPI document](https://skmtc.dev/billcommons/apis/bill-commons-api/revisions/bfb8cd50a317?raw)