CourtListener Scraper

Scrape CourtListener — Free Law Project's open database of US case law (8M+ opinions), federal court dockets (60M+ from PACER/RECAP), oral argument audio recordings, and judge biographies. HTTP-only via the official courtlistener.com/api/rest/v4/ endpoint. Anonymous reads work for all search modes; an optional API token unlocks single-resource lookups and citation resolution.

What this actor does

• 11 modes — search opinions, dockets, RECAP filings, oral arguments; lookup by ID; courts directory; citation resolution; URL fetch
• Universal IDs — opinion cluster IDs, docket IDs, person (judge) IDs, court ID slugs
• Filters — court, judge, date filed, citation, neutral cite, docket number, precedential status, min citation count
• PDF & MP3 storage links — direct CDN URLs for opinion PDFs, RECAP filings, and oral argument audio
• Empty fields are omitted

Modes

Mode	What it returns	Required input
searchOpinions	Free-text search of US case law	searchQuery
searchDockets	Federal court dockets (RECAP / PACER)	searchQuery
searchRecapDocuments	Individual filings within RECAP dockets	searchQuery
searchOralArguments	Oral argument audio recordings	searchQuery
byOpinion	Single opinion by cluster ID	opinionId
byDocket	Single docket	docketId
byJudge	Judge / person profile	judgeId
byCourt	Single court	courtId
listCourts	All 3,000+ courts indexed by CourtListener	—
citationLookup	Resolve citation text → opinion clusters (requires apiToken)	citationText
byUrl	Fetch by CourtListener URL	urls

Output per record

Common fields:

• recordType — opinion / docket / recapDocument / oralArgument / judge / court / citationLookup
• caseName, court, courtId, courtCitation
• dateFiled, dateArgued, dateTerminated
• docketNumber, docketId, clusterId
• courtListenerUrl — canonical URL
• absoluteUrl — relative URL for the resource on CourtListener
• scrapedAt — ISO 8601 UTC timestamp

Opinion-specific:

• judge, panel[], status (Published / Unpublished / Errata / ...)
• citations[], neutralCite, lexisCite, scdbId, citeCount
• siblingOpinionIds[]
• opinions[] (per-opinion sub-records with id, type, pdfUrl, downloadUrl, snippet, citesOpinionIds[], perCuriam, sha1)

Docket-specific:

• assignedTo, cause, natureOfSuit, jurisdictionType, juryDemand, chapter
• parties[], attorneys[], firms[]
• pacerCaseId
• recapDocuments[] (id, documentType, shortDescription, pdfUrl, isAvailable, pageCount, ...)

Oral argument-specific:

• mp3Url, downloadUrl, durationSeconds, fileSizeBytes
• audioId, judge

Judge-specific:

• fullName, nameFirst, nameMiddle, nameLast, nameSuffix
• dateDob, dateDod, dobCity, dobState, gender, religion, race[]
• politicalAffiliations[], abaRatings[]
• educations[] (school, degreeLevel, degreeYear)
• positions[] (positionType, court, appointer, dateStart, dateTermination)

Court-specific:

• id, fullName, shortName, citationString, jurisdiction, url
• startDate, endDate, inUse, hasOpinionScraper, hasOralArgumentScraper
• parentCourt, appealsTo[]

Input

Field	Type	Default	Description
mode	enum	searchOpinions	Mode dispatcher
searchQuery	string	first amendment	Free-text query
court	enum	any	Court ID slug (curated list of major US courts)
judge	string	–	Judge name filter
filedAfter, filedBefore	YYYY-MM-DD	–	Filing date range
citation	string	–	Citation text filter
neutralCite	string	–	Neutral citation filter
docketNumber	string	–	Docket number text filter
status	enum	any	Precedential status (Published / Unpublished / ...)
orderBy	enum	score desc	Sort order
opinionId	string	–	Opinion cluster ID (mode=byOpinion)
docketId	string	–	Docket ID (mode=byDocket)
judgeId	string	–	Person ID (mode=byJudge)
courtId	string	–	Court ID slug (mode=byCourt)
citationText	textarea	–	Citation text to resolve (mode=citationLookup)
urls	array	–	CourtListener URLs (mode=byUrl)
minCitationCount	int	–	Drop opinions cited fewer times than this
highlight	bool	true	Include matched snippet text
apiToken	string (secret)	–	Optional API token (5,000 req/hr)
maxItems	int	50	1–10000

Example: Supreme Court free speech cases since 2000

{
  "mode": "searchOpinions",
  "searchQuery": "free speech",
  "court": "scotus",
  "filedAfter": "2000-01-01",
  "status": "Published",
  "orderBy": "citeCount desc",
  "maxItems": 50
}

Example: 9th Circuit patent dockets 2024

{
  "mode": "searchDockets",
  "searchQuery": "patent infringement",
  "court": "ca9",
  "filedAfter": "2024-01-01",
  "filedBefore": "2024-12-31"
}

Example: SCOTUS oral arguments

{
  "mode": "searchOralArguments",
  "searchQuery": "miranda rights",
  "court": "scotus"
}

Example: judge profile

{
  "mode": "byJudge",
  "judgeId": "3045"
}

Example: list all courts

{
  "mode": "listCourts",
  "maxItems": 5000
}

Use cases

• Legal research — pull opinion text for citator analysis, AI legal assistants, research databases
• Litigation tracking — monitor RECAP dockets for new filings in patent / IP / antitrust matters
• Judicial analytics — judge biography + ABA ratings + appointment data for bench analytics
• Citator services — citation graphs from opinion-cites-opinion relationships
• Oral-argument NLP — MP3 + snippet text for SCOTUS/circuit court argument analysis
• Court directory mining — comprehensive list of US courts with jurisdictional metadata

FAQ

Do I need an API token? No, for search modes. CourtListener's search API is fully open. A token is required for byOpinion / byDocket (single-resource endpoints), citationLookup, and any rate-limited heavy use. Tokens are free at https://www.courtlistener.com/profile/api/.

Why do search modes work without a token? Free Law Project explicitly publishes the search index for public/research use. Single-record endpoints (/opinions/{id}/, /dockets/{id}/) are gated to discourage scraping the full database one record at a time.

What's the difference between byOpinion and the search endpoint? byOpinion looks up a specific cluster ID via q=cluster_id:N. It uses search internally so it works without auth. The actor returns the same fields as a search hit.

What's RECAP? RECAP is Free Law Project's project to liberate PACER documents. Every time a paying PACER user views a docket, it's archived to RECAP and made free for everyone forever. CourtListener indexes ~60M filings from 1.4M dockets.

Are opinion PDFs included? Each opinion record includes a pdfUrl pointing at storage.courtlistener.com. PDFs are publicly accessible.

Are RECAP filings accessible? Most are not — isAvailable: false means the document hasn't been purchased yet. isAvailable: true records have a free pdfUrl you can download.

How fresh is the data? CourtListener scrapes most courts daily; SCOTUS and circuit court opinions appear within hours. Oral arguments appear same-day.

What's the difference between an opinion and a cluster? A cluster is a single legal decision. An opinion is a piece of writing within that decision (majority, concurrence, dissent). One cluster has 1-N opinions. The actor returns one record per cluster with all sub-opinions nested.

Limitations

• Single-resource endpoints (/opinions/{id}/, /dockets/{id}/, /clusters/{id}/, /citation-lookup/) require an API token. The actor uses search-by-ID (q=cluster_id:N) for byOpinion/byDocket so they work without auth.
• RECAP filings are only downloadable when isAvailable: true. Sealed / unpurchased filings show metadata only.
• The full-text snippet is capped at 1,000 characters per opinion to keep payloads reasonable. Use the pdfUrl to fetch full text.