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

# Lookup Bills Get

`GET /api/v1/bills/lookup`

## Request

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

GET alias of `/bills/batch` under the `/bills/lookup` name.

## 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`. 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)