---
title: "Everything we hold for one RIN"
method: GET
path: "/api/v1/us/rulemaking/rins/{rin}"
tags: ["US Rulemaking"]
---

# Everything we hold for one RIN

`GET /api/v1/us/rulemaking/rins/{rin}`

## Request

- Base URL: `https://api.vaquill.ai`
- URL: `https://api.vaquill.ai/api/v1/us/rulemaking/rins/{rin}`
- 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/rins/:rin/get.ts> (a function with typed inputs; its response is checked against the schema)

The latest Unified Agenda entry and edition span, OIRA reviews with their outcome and the Federal Register document each one cleared, Regulations.gov dockets (with how many documents are open for comment), Federal Register documents by role (proposed, final, correction, extension), CFR parts, public laws and related RINs, each with the basis and quality of the link. `coverage` lists what we do not hold for this RIN.

## Path parameters

- `rin` string, required: Regulation Identifier Number `NNNN-AANN`; lower case is accepted.

## 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

- RinResponse: Response for `GET /us/rulemaking/rins/{rin}`: everything we hold about one rulemaking.
  - `processingTimeMs` number: Server-side time in milliseconds, not billed on.
  - `creditsConsumed` integer: Credits charged for this call. 0 when not charged or refunded.
  - `rin` string, required
  - `title` string, nullable
  - `agencyCode` string, nullable
  - `status` string, nullable: Spine status: pending, final, final_only, ambiguous, withdrawn, umbrella_excluded.
  - `stage` string, nullable: Stage of the newest Unified Agenda entry.
  - `isUmbrella` boolean, nullable: An umbrella RIN covers many unrelated documents; no proposal-to-final pairing is claimed.
  - `umbrellaBasis` string, nullable
  - `agenda` AgendaSummary
    - `editions` integer, required: Editions of the Unified Agenda that carry this RIN.
    - `firstEdition` string, nullable
    - `lastEdition` string, nullable
    - `latest` AgendaLatest
      - `editionId` string, required: Unified Agenda edition id `YYYYMM`.
      - `season` string, nullable
      - `year` integer, nullable
      - `runDate` string, date, nullable
      - `title` string, nullable
      - `stage` string, nullable
      - `priority` string, nullable
      - `rinStatus` string, nullable
      - `major` string, nullable
      - `agencyCode` string, nullable
      - `agencyName` string, nullable
      - `agencyAcronym` string, nullable
      - `parentAgencyName` string, nullable
      - `furtherInfoUrl` string, nullable: Served only when it is an official (.gov or .mil) link.
      - `publicCommentUrl` string, nullable
      - `sourceUrl` string, nullable
  - `reviews` ReviewItem[]
    - `reviewKey` string, required
    - `stage` string, nullable
    - `stageNorm` string, nullable
    - `title` string, nullable
    - `dateReceived` string, date, nullable
    - `dateCompleted` string, date, nullable
    - `decision` string, nullable: OIRA's decision as printed.
    - `economicallySignificant` boolean, nullable
    - `status` string, nullable: `pending` or `concluded`.
    - `agencyAcronym` string, nullable
    - `meetingCount` integer
    - `linkStatus` string, nullable: `linked`, `ambiguous`, `umbrella_rin`, `no_candidate`, `no_fr_for_rin`, `pending` or `not_applicable`.
    - `frActId` string, nullable: Federal Register act id, set only when `linkStatus` is `linked`.
    - `frCitation` string, nullable
    - `frPublicationDate` string, date, nullable
  - `dockets` DocketLink[]
    - `docketId` string, required
    - `agencyId` string, nullable
    - `docketType` string, nullable
    - `title` string, nullable
    - `commentCount` integer, nullable
    - `lastModifiedAt` string, date-time, nullable
    - `documentCount` integer
    - `openDocumentCount` integer
    - `sourceUrl` string, required
  - `federalRegister` FederalRegisterLink[]
    - `documentNumber` string, required
    - `role` 'proposed' | 'final' | 'correction' | 'extension' | 'other', required
    - `actId` string, nullable
    - `citation` string, nullable
    - `publicationDate` string, date, nullable
    - `title` string, nullable
    - `docKind` string, nullable
    - `action` string, nullable
    - `basis` string, required
    - `quality` 'verified' | 'candidate' | 'ambiguous', required
  - `cfrParts` CfrPartLink[]
    - `cfrTitle` integer, required
    - `cfrPart` string, required
    - `basis` string, required
    - `quality` 'verified' | 'candidate' | 'ambiguous', required
  - `publicLaws` SimpleLink[]
    - `key` string, required
    - `basis` string, required
    - `quality` 'verified' | 'candidate' | 'ambiguous', required
  - `craDisapprovals` SimpleLink[]
    - `key` string, required
    - `basis` string, required
    - `quality` 'verified' | 'candidate' | 'ambiguous', required
  - `relatedRins` SimpleLink[]
    - `key` string, required
    - `basis` string, required
    - `quality` 'verified' | 'candidate' | 'ambiguous', required
  - `coverage` CoverageNote[]: What we hold and do not hold for this RIN.
    - `source` string, required
    - `held` boolean, required
    - `note` string, nullable
  - `asOf` string, date-time, nullable: When the cross-link spine was last built.

## Other responses

- `401`: Missing, invalid or revoked API key. Not charged.
- `402`: Insufficient credits. Nothing was done and nothing was charged.
- `404`: We hold nothing for this RIN. Refunded.
- `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)