---
title: "List and filter Regulations.gov dockets"
method: GET
path: "/api/v1/us/rulemaking/dockets/list"
tags: ["US Rulemaking"]
---

# List and filter Regulations.gov dockets

`GET /api/v1/us/rulemaking/dockets/list`

## Request

- Base URL: `https://api.vaquill.ai`
- URL: `https://api.vaquill.ai/api/v1/us/rulemaking/dockets/list`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/vaquill/apis/vaquill-developer-api/docs/api/v1/us/rulemaking/dockets/list/get.ts> (a function with typed inputs; its response is checked against the schema)

Dockets, most recently modified first, filtered by agency, type, RIN and modified date. One page is one charge; an empty page is charged (it is an answer). `nextCursor` is bound to the filters that produced it.

## Query parameters

- `agencyId` string, nullable
- `docketType` string, nullable
- `rin` string, nullable: Normalised RIN.
- `hasRin` boolean, nullable
- `modifiedSince` string, date-time, nullable
- `modifiedUntil` string, date-time, nullable
- `limit` integer: Page size, 1 to 100.
- `cursor` string, nullable: `nextCursor` of the previous page; same filters.

## Headers

- `Idempotency-Key` string, nullable: Optional. 16 to 255 visible ASCII characters (a UUIDv4 is ideal). A retry with the same key and the same request replays the original 2xx response for 24 hours without charging again. The same key with a different request is rejected. Scope is the API key, method, path and body. The stored response body is a query-derived cache controlled by the account's data retention setting cacheQueryDerivedData: when it is false the body is never stored and a retry answers 409 idempotency_replay_unavailable, without charging again.

## Response `200`

Successful Response

- DocketListResponse: Response for `GET /us/rulemaking/dockets`.
  - `processingTimeMs` number: Server-side time in milliseconds, not billed on.
  - `creditsConsumed` integer: Credits charged for this call. 0 when not charged or refunded.
  - `dockets` DocketSummary[], required
    - `docketId` string, required: Regulations.gov docket id.
    - `agencyId` string, required: Regulations.gov agency id.
    - `docketType` string, nullable: `Rulemaking` or `Nonrulemaking`.
    - `title` string, nullable
    - `rin` string, nullable: Regulation Identifier Number, normalised. Regulations.gov's value when it has one, otherwise the single RIN our cross-link spine holds as verified for this docket (see `rinSource`). Null when neither exists, or when the spine names several RINs (no pick is made).
    - `rinSource` 'regulations_gov' | 'spine', nullable: Where `rin` came from: `regulations_gov` (the publisher) or `spine` (our verified cross-link). Null when `rin` is null.
    - `spineRin` string, nullable: Set only when the spine holds a verified RIN that DIFFERS from the publisher's `rin`. `rin` stays the publisher's value.
    - `lastModifiedAt` string, date-time, nullable: Regulations.gov `lastModifiedDate`.
    - `commentCount` integer, nullable: Comments received. Null means NOT MEASURED, never zero. See `commentCountAsOf`.
    - `commentCountAsOf` string, date-time, nullable: When we measured `commentCount`.
    - `sourceUrl` string, required: The docket page on regulations.gov.
    - `asOf` string, date-time, nullable: When we last saw this docket at the publisher.
  - `nextCursor` string, nullable: Opaque. Pass it back with the same filters for the next page.

## Other responses

- `401`: Missing, invalid or revoked API key. Not charged.
- `402`: Insufficient credits. Nothing was done and nothing was charged.
- `409`: Idempotency conflict. `idempotency_in_progress`: the original request with this key is still running (retry after `Retry-After`). `idempotency_replay_unavailable`: it completed but its response was too large to replay; nothing is charged again, so check the credit balance instead of retrying.
- `422`: Validation error: `detail` plus one `errors` entry per rejected field. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different request.
- `429`: Rate limit exceeded.
- `503`: The rulemaking database is unavailable. Refunded.

---

[API](https://skmtc.dev/vaquill/apis/vaquill-developer-api.md) - [All operations](https://skmtc.dev/vaquill/apis/vaquill-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vaquill/apis/vaquill-developer-api/revisions/fbac9b87775e?raw)