---
title: "RETIRED — US court opinions (410 corpus_retired)"
method: GET
path: "/us-law/opinions"
deprecated: true
---

# RETIRED — US court opinions (410 corpus_retired)

`GET /us-law/opinions`

## Request

- Base URL: `https://ai-law-tracker.com/api/v1`
- URL: `https://ai-law-tracker.com/api/v1/us-law/opinions`
- Auth: one of:
  - none
  - API key in header `X-API-Key`
  - HTTP bearer

> **Deprecated.**

⛔ RETIRED 2026-08-22 — THIS ENDPOINT NOW RETURNS 410 `corpus_retired`.

The US court-opinion corpus (988,554 records) is out of scope for this API and is no longer served. Opinion identifications remain available at https://www.courtlistener.com. No other /v1 surface is affected, and nothing is charged against your record budget for this path — the refusal is returned before the tier gate and before any metering.

The original description is kept verbatim below, as the record of what this endpoint did. A restore therefore reinstates a KNOWN contract rather than a reconstructed one.

─────────────────────────────────────────────────────────────

Published opinions filed 2015-01-01 onward from federal appellate courts and state supreme/appellate courts. Each record IDENTIFIES a decision — case name, court, filing date, docket number, reporter citation, and how many later opinions cite it — and links to the full decision at `absolute_url`.

THERE IS NO OPINION TEXT AND NO HOLDING IN THIS CORPUS. `q` is a websearch full-text match over the CASE NAME only (quoted phrases and -exclusion work: `"Trump v. Cook"`, `monsanto -durnell`), and every response that ran one says so in `meta.search_field`. Do not describe this endpoint as searching the text of decisions.

METERED ON RECORDS SERVED, on the SAME budget as /v1/us-law rather than a second one. That is deliberate: a separate allowance would have widened every existing key the day this dataset shipped. Every response carries `meta.record_budget`; exhausting it returns 429 `record_budget_exceeded`.

TWO LIMITS COME FROM THE SIZE OF THE TABLE, NOT FROM YOUR TIER, and they apply identically at every tier including Enterprise. (1) `meta.total` is the PLANNER’S ESTIMATE above 1,000 rows — it measured 53% low on one full-text query — so it is always accompanied by `meta.total_is_estimate`; pass `count=exact` for the true number, at up to ~3.3 s. (2) `sort=citation_count` and `cited_min` have no index behind them and are refused with 400 unless the query already carries a narrowing filter; unfiltered, they are cancelled by the database statement timeout.

PRODUCT SCOPE: this endpoint belongs to the US Law Platform. A key licensed only for AI Law Tracker is served here at the public (keyless) level, reported in `X-ALT-Product-Scope` — not refused.

## Query parameters

- `court` string
- `court_level` string
- `jurisdiction_level` string
- `cluster_id` string
- `filed_from` string, date
- `filed_to` string, date
- `q` string
- `citation` string
- `citation_prefix` string
- `cited_min` integer
- `sort` 'date_filed' | 'citation_count'
- `order` 'asc' | 'desc'
- `count` 'estimated' | 'exact'
- `limit` integer
- `offset` integer

## Response `200`

Matching opinions, plus the record-budget state.

- object
  - `api_version` string
  - `data` CourtOpinion[]
    - `cluster_id` integer: CourtListener cluster id — the stable identifier, and the path parameter of the detail endpoint.
    - `case_name` string: The caption. This is the ONLY field `q` searches. Never withheld at any tier.
    - `court_id` string: Court slug, e.g. scotus, iowa, nyappdiv. See /us-law/courts for the full list.
    - `court_name` string: Never withheld at any tier.
    - `court_citation_string` string, nullable: The court’s reporter abbreviation, e.g. "Iowa". Withheld in the trimmed (basic) envelope.
    - `court_jurisdiction` 'F' | 'S' | 'SA': The indexed jurisdiction code the court_level / jurisdiction_level filters resolve onto.
    - `court_level` 'federal_appellate' | 'state_supreme' | 'state_appellate'
    - `date_filed` string, date: ALWAYS read alongside date_filed_is_approximate.
    - `date_filed_is_approximate` boolean: True when the filing date is our source’s approximation rather than a stated date — 58,828 of 988,554 records. NEVER withheld at any tier, including the keyless envelope: shipping date_filed without this flag would present a guess as a fact to people who compute deadlines from it.
    - `precedential_status` string: Every record currently held is "Published".
    - `docket_id` integer, nullable: Withheld in the trimmed (basic) envelope.
    - `docket_number` string, nullable: Withheld in the trimmed (basic) envelope. NOT a filter — see the endpoint description.
    - `primary_citation` string, nullable: Reporter citation, e.g. "2022 OK 38". 541,629 of 988,554 records carry one. Never withheld at any tier.
    - `citation_count` integer: How many later opinions cite this one. Withheld in the trimmed (basic) envelope.
    - `absolute_url` string: Where the decision itself is. Never withheld at any tier — it is how you check our work.
    - `slug` string, nullable: Withheld in the trimmed (basic) envelope.
    - `source_authority` string: courtlistener. Withheld in the trimmed (basic) envelope.
    - `bulk_edition` string, date, nullable: Which source bulk edition this row came from. Withheld in the trimmed (basic) envelope.
    - `retrieved_at` string, date-time: When WE fetched it — not when the court decided it. Withheld in the trimmed (basic) envelope.
  - `meta` object
    - `total` integer: READ total_is_estimate BEFORE quoting this number.
    - `total_is_estimate` boolean: true when `total` is the query planner’s estimate rather than a count. Set whenever the result exceeds 1,000 rows and `count=exact` was not requested.
    - `count` integer
    - `limit` integer
    - `offset` integer
    - `tier` string: The tier you were SERVED at — `anon` when out of product.
    - `fields` 'basic' | 'full'
    - `gated` string[]: Which parameters your tier clamped.
    - `search_field` string, nullable: Present when `q` ran. Always `case_name`.
    - `corpus` object: `full_text: false` plus where the text actually is.
    - `record_budget` object
      - `enforced` boolean
      - `records_remaining_today` integer, nullable
      - `records_remaining_period` integer, nullable
    - `disclaimer` string
    - `upgrade` string, nullable
  - `attribution` string

## Other responses

- `400`: invalid_request — an unparseable filter, or an unindexed sort/filter without a narrowing filter.
- `403`: tier_upgrade_required.
- `429`: Rate limited, or `record_budget_exceeded`.
- `503`: Corpus backend unavailable.

---

[API](https://skmtc.dev/ai-law-tracker/apis/ai-law-tracker-public-laws-api.md) · [All operations](https://skmtc.dev/ai-law-tracker/apis/ai-law-tracker-public-laws-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ai-law-tracker/apis/ai-law-tracker-public-laws-api/revisions/25403268a853?raw)