API returns ~10M non-SCOTUS cases when filtering by court=scotus

[mroswell]

What happened?

Claude.AI is helping me with this. Here's what it found. (two versions, one more general and one with more detail)
Is Claude right, or is CourtListener right?

When querying the /clusters/ endpoint with court=scotus, the API returns cases that are clearly from state courts and lower federal courts, not the Supreme Court of the United States.

Evidence

Query Used

curl -H "Authorization: Token [TOKEN]" \
  "https://www.courtlistener.com/api/rest/v3/clusters/?court=scotus&order_by=-date_filed&page_size=20"

Examples of Non-SCOTUS Cases Returned

1. Mongeon Bay Properties, LLC v. Town of Colchester

   • Cluster ID: 10778750
   • Reporter Citation: "2026 VT 1" (Vermont Reports)
   • Date Filed: 2026-01-23
   • This is clearly a Vermont Supreme Court case

2. State v. Wallace Cable

   • Cluster ID: 10778747
   • Syllabus mentions "Rhode Island Rule of Evidence 803(4)"
   • This is clearly a Rhode Island Supreme Court case

3. Moore v. Brooks

   • Cluster ID: 10778746
   • Reporter Citation: "2026 NCBC 6" (North Carolina Business Court)
   • This is clearly a North Carolina Business Court case

4. Chad Everette Urrutia v. The State of Wyoming

   • Cluster ID: 10778737
   • Reporter Citation: "2026 WY 14" (Wyoming Reports)
   • This is clearly a Wyoming Supreme Court case

5. Ricky R. House, Jr. v. State of Indiana

   • Cluster ID: 10778743
   • Judges listed: "Altice, May, Foley"
   • This is clearly an Indiana Court of Appeals case

6. State of Louisiana v. Carl England

   • Cluster ID: 10778744
   • This is clearly a Louisiana Court of Appeal case

Additional Data Quality Issues

Some cases returned have impossible future filing dates:

• Case dated 2041-02-11 (Mary Hersey v. WPB Partners LLC)
• Case dated 2035-11-03 (State of Minnesota v. Jeremy Thomas Herrera)
• Cases dated 2026-10-20, 2026-06-26, etc.

Expected Behavior

When filtering by court=scotus, the API should return only cases from the Supreme Court of the United States, which would have:

• Reporter citations like "U.S.", "S. Ct.", or "L. Ed."
• No state-specific legal citations
• Reasonable filing dates (not in the future)

Scope of Issue

The API reports "count": 9970832 results for court=scotus. Given that the Supreme Court has decided fewer than 10,000 cases in its entire history, this suggests the vast majority of these ~10 million results are incorrectly classified.

Questions

1. Is there a different API parameter or endpoint I should use to reliably filter for SCOTUS cases only?
2. Is this a known issue with court classification in the database?
3. Are there plans to fix the court tagging for these cases?

---

Technical Details for Reproduction

API Endpoint: https://www.courtlistener.com/api/rest/v3/clusters/

Parameters:

• court=scotus
• order_by=-date_filed
• page_size=20

Date of Testing: January 23, 2026

Expected SCOTUS Indicators:

• Reporter citations: "U.S.", "S. Ct.", "L. Ed."
• Court docket from SCOTUS jurisdiction
• Reasonable filing dates

Observed State Court Indicators:

• Reporter citations: "VT", "WY", "NCBC", etc.
• State-specific legal citations in syllabus/headnotes
• State court judge names

CourtListener SCOTUS Filtering Issue - Technical Documentation

Issue Summary

State and lower court cases are returned when filtering for Supreme Court of the United States cases in the CourtListener API.

Reproduction Steps

1. Query the Clusters Endpoint for SCOTUS Cases

curl -H "Authorization: Token YOUR_TOKEN_HERE" \
  "https://www.courtlistener.com/api/rest/v3/clusters/?court=scotus&order_by=-date_filed&page_size=20"

2. Verify Court ID is Correct

First, confirm that 'scotus' is the correct court identifier:

curl -H "Authorization: Token YOUR_TOKEN_HERE" \
  "https://www.courtlistener.com/api/rest/v3/courts/scotus/"

Response:

{
  "id": "scotus",
  "full_name": "Supreme Court of the United States",
  "short_name": "Supreme Court",
  "url": "https://www.supremecourt.gov/",
  "jurisdiction": "F"
}

✅ Confirmed: 'scotus' is the correct identifier for the Supreme Court of the United States.

---

Problem: Non-SCOTUS Cases Returned

Example 1: Vermont Supreme Court Case

Query Result:

{
  "resource_uri": "https://www.courtlistener.com/api/rest/v3/clusters/10778750/",
  "id": 10778750,
  "absolute_url": "/opinion/10778750/mongeon-bay-properties-llc-v-town-of-colchester/",
  "docket_id": 72181187,
  "case_name": "Mongeon Bay Properties, LLC v. Town of Colchester",
  "date_filed": "2026-01-23",
  "citations": [{
    "volume": "2026",
    "reporter": "VT",
    "page": "1",
    "type": 8
  }],
  "precedential_status": "Published"
}

Evidence this is NOT a SCOTUS case:

• Reporter citation: "VT" (Vermont Reports)
• Case involves local Vermont property dispute
• No SCOTUS jurisdiction indicators

---

Example 2: Rhode Island Supreme Court Case

Query Result:

{
  "resource_uri": "https://www.courtlistener.com/api/rest/v3/clusters/10778747/",
  "id": 10778747,
  "case_name": "State v. Wallace Cable",
  "date_filed": "2026-01-23",
  "syllabus": "The defendant was found guilty on one count of first-degree child molestation sexual assault. On appeal, the defendant claimed that the trial justice erred when he permitted the state to introduce into evidence multiple out-of-court statements concerning what the complaining witness told a treating physician about the alleged charged and uncharged sexual assaults. The Supreme Court concluded that but for a single statement, the defendant failed to preserve the hearsay arguments for appeal. With respect to the one statement that was preserved concerning the defendant's fear of imprisonment, the Supreme Court concluded that the trial justice did not abuse his discretion in admitting the hearsay statement pursuant to Rhode Island Rule of Evidence 803(4)..."
}

Evidence this is NOT a SCOTUS case:

• Syllabus references "Rhode Island Rule of Evidence 803(4)"
• State criminal appeal (typical state supreme court jurisdiction)
• No federal question apparent

---

Example 3: North Carolina Business Court Case

Query Result:

{
  "resource_uri": "https://www.courtlistener.com/api/rest/v3/clusters/10778746/",
  "id": 10778746,
  "case_name": "Moore v. Brooks",
  "date_filed": "2026-01-23",
  "citations": [{
    "volume": "2026",
    "reporter": "NCBC",
    "page": "6",
    "type": 4
  }]
}

Evidence this is NOT a SCOTUS case:

• Reporter citation: "NCBC" (North Carolina Business Court)
• This is a state trial court, not even a state supreme court

---

Example 4: Wyoming Supreme Court Case

Query Result:

{
  "resource_uri": "https://www.courtlistener.com/api/rest/v3/clusters/10778737/",
  "id": 10778737,
  "case_name": "Chad Everette Urrutia v. The State of Wyoming",
  "date_filed": "2026-01-23",
  "citations": [{
    "volume": "2026",
    "reporter": "WY",
    "page": "14",
    "type": 8
  }]
}

Evidence this is NOT a SCOTUS case:

• Reporter citation: "WY" (Wyoming Reports)

---

Example 5: Indiana Court of Appeals Case

Query Result:

{
  "resource_uri": "https://www.courtlistener.com/api/rest/v3/clusters/10778743/",
  "id": 10778743,
  "case_name": "Ricky R. House, Jr. v. State of Indiana",
  "date_filed": "2026-01-23",
  "judges": "Altice, May, Foley",
  "disposition": "Affirmed"
}

Evidence this is NOT a SCOTUS case:

• Judges listed: Altice, May, Foley (Indiana Court of Appeals judges)
• Case name format typical of state criminal appeals

---

Example 6: Louisiana Court of Appeal Case

Query Result:

{
  "resource_uri": "https://www.courtlistener.com/api/rest/v3/clusters/10778744/",
  "id": 10778744,
  "case_name": "State Of Louisiana v. Carl England",
  "date_filed": "2026-01-23"
}

---

Additional Data Quality Issues: Future Dates

Case with 2041 Filing Date

{
  "id": 10698117,
  "case_name": "Mary Hersey v. WPB Partners LLC",
  "date_filed": "2041-02-11",
  "citations": [{
    "volume": "2014",
    "reporter": "DNH",
    "page": "029"
  }]
}

Case with 2035 Filing Date

{
  "id": 10730588,
  "case_name": "State of Minnesota v. Jeremy Thomas Herrera",
  "date_filed": "2035-11-03"
}

---

Expected SCOTUS Case Indicators

Legitimate Supreme Court of the United States cases should have:

1. Reporter Citations:

   • "U.S." (United States Reports - official reporter)
   • "S. Ct." (Supreme Court Reporter)
   • "L. Ed." (Lawyers' Edition)

2. Reasonable Filing Dates:

   • Not in the future
   • Within plausible date ranges

3. SCOTUS Docket Numbers:

   • Format like "No. 22-1234"
   • Not state court docket numbers

4. Federal Jurisdiction:

   • Federal questions
   • Constitutional issues
   • Interstate disputes
   • Cases involving federal law

---

Scale of the Problem

API Response:

{
  "count": 9970832
}

The API reports 9,970,832 cases with court=scotus.

Historical Reality:

• The Supreme Court has decided fewer than 10,000 cases in its entire 235+ year history
• The Court typically decides 60-80 cases per year currently

Conclusion:
Approximately 99.9% of the cases returned by court=scotus filter are incorrectly classified.

---

Test Cases for Validation

If the filtering were working correctly, querying recent SCOTUS cases should return:

1. Cases with "U.S.", "S. Ct.", or "L. Ed." citations
2. Cases involving federal questions
3. Cases with SCOTUS-style docket numbers
4. Cases decided by the nine Supreme Court Justices

---

Attempted Workarounds

Using cluster__court Parameter on Opinions Endpoint

curl -H "Authorization: Token YOUR_TOKEN_HERE" \
  "https://www.courtlistener.com/api/rest/v3/opinions/?cluster__court=scotus&order_by=-date_filed&page_size=5"

Result: Returns the same incorrectly classified cases (e.g., Ohio Court of Appeals case "Geisenfeld v. Geisenfeld, 2026-Ohio-205")

---

System Information

• Test Date: January 23, 2026
• API Base URL: https://www.courtlistener.com/api/rest/v3/
• Endpoints Tested: /clusters/, /opinions/
• Authentication: Token-based (working correctly)

---

Request for Clarification

1. Is there a different filter or endpoint that reliably returns only SCOTUS cases?
2. What is the cause of the court misclassification?
3. Is there a timeline for fixing this data quality issue?
4. Should we use a different approach to identify authentic SCOTUS cases via the API?

---

Additional Notes

This issue prevents reliable automated tracking of Supreme Court decisions. The current state requires extensive manual filtering to separate actual SCOTUS cases from the ~10 million incorrectly tagged state court cases.

Expected behavior

No response

Actual behavior

No response

Steps to reproduce

No response

Screenshots

No response

What is the severity of the bug?

Unknown

[mroswell]

I updated to v4, and still have the scotus filter issue.

[mlissner]

You need to understand the filters and data model correctly, and Claude simply does not.

Opinions go through clusters and dockets to the court model, so you need to filter them with ?clusters__docket__court=scotus.

Clusters go through dockets to courts, so you need to filter them like: ?docket__court=scotus.

Dockets just go through courts, so you just need: ?court=scotus.

Courts don't go through anything, so you just need /scotus/

This is all off the top of my head, so they might not be exactly right, but the API is workign properly, so I made this a discussion, not a bug. I hope this helps!

[mroswell]

Thank you!
?cluster__docket__court=scotus did the trick.
(singular "cluster" not "clusters")

(I'm building a class exercise on tagging with AI and GitHub Actions. This API is a nice find; Still navigating my way around it, though.)

[mroswell]

Well, now I'm doing battle with dates. If anyone wants to help, my repo is at:
https://github.com/mroswell/supreme-court-decisions
And the results are in the JSON and CSV file.
(The README is not up to date. Storm prep and class preparation calls...)