---
title: "List Changes"
method: GET
path: "/api/v1/changes"
tags: ["changes"]
---

# List Changes

`GET /api/v1/changes`

## Request

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

Bill changes in commit order, oldest first.

Poll with the `next_cursor` from the previous response. `has_more` false
means you are caught up; keep the cursor and poll again later.

## Query parameters

- `cursor` string, nullable: Opaque cursor from a previous response's `next_cursor`. Omit to start from the beginning of the log.
- `ids` string, nullable: Comma-separated bill UUIDs -- returns changes only for these bills. Up to 200 per request. This is what makes the feed usable for a watchlist: without it a caller tracking 160 bills must page the entire national delta and filter client-side.
- `jurisdiction` string, nullable: Restrict to one jurisdiction abbreviation, e.g. NC
- `kind` string, nullable: Restrict to one change kind: created, status, actions, sponsors, text, metadata, votes.
- `per_page` integer

## Response `200`

Successful Response

- ChangeFeedEnvelope: Response for `/changes`. Pass `next_cursor` back verbatim to continue. It is opaque on purpose: consumers persist cursors for months, so publishing the raw ordering key would freeze it, and this way the ordering scheme can change later without invalidating a single stored cursor. On an empty page `next_cursor` echoes the cursor you sent, so a polling loop can store the response unconditionally and never accidentally rewind or skip.
  - `data` ChangeEvent[], required
    - `cursor` string, required
    - `kind` string, required: created | status | actions | sponsors | text | metadata | votes. `text` means document text became available -- the bill is now searchable and diffable. `votes` means one or more vote events were recorded; `detail` carries the tally when the source provides one.
    - `changed_at` string, date-time, required
    - `detail` string, nullable: Human-readable specifics, e.g. 'in_committee -> enacted'.
    - `bill` BillSummary: Row shape used in list/search results (lighter than the detail view).
      - `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
  - `next_cursor` string, required
  - `has_more` boolean, required
  - `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)