Case / Docket Search
Find cases by party name, judge, or court across all federal jurisdictions.
search tabCase Law Search
Search published opinions and decisions by keyword or natural language with semantic search.
semantic searchJudge Lookup
Find federal judges by name and court. Returns bio, affiliations, and positions.
search tabJudge Profile
One-click bio, positions, and recent assigned dockets for a single judge.
featuredJudge Disclosures
View a judge's financial disclosure filings — investments, positions, gifts, debts, and reimbursements by year.
newRECAP Archive
Access free PACER documents through the RECAP archive — no PACER fees.
free pacerCourt Directory
Browse all available federal courts by jurisdiction type.
search tabCSV Export
Download any result set as CSV with one click — including judge docket lists.
all tabsResponsive Design
Works on desktop, tablet, and mobile. Pagination for large result sets.
uiGet Your API Token
Sign up for a free account at CourtListener's API page and grab your token.
Configure Your Token
Copy .env.example to .env and paste your token:
cp .env.example .env
# edit .env and replace your-token-here with your real tokenapp.py auto-loads .env on startup. The file is gitignored so the token stays local.
Install Dependencies
pip install fastapi uvicorn requestsRun the Backend Server
python app.pyThe server starts on http://localhost:8000. Open /search.html for the web interface or /docs for the interactive API explorer.
Select a search type from the tabs: Cases, Case Law, Judges, Judge Profile, Judge Disclosures, RECAP Archive, or Courts.
Enter your search criteria and optionally pick a court from the dropdown to narrow results.
Click Search to submit. Results appear below with pagination controls.
Click Export CSV in the results header to download the current result set.
On the Case Law tab, click the &/? toggle to switch between keyword and semantic search. Semantic search finds cases by meaning — e.g., "tenant evicted for having a dog" finds pet-related housing cases, not just results containing those exact words. Wrap terms in "quotes" for hybrid keyword + semantic matching.
The Judge Profile tab returns a single judge's bio, positions, and recent dockets in one view. The Judge Disclosures tab shows their financial disclosure filings — investments, outside positions, gifts, debts, and reimbursements organized by year.
| Endpoint | Description |
|---|---|
| GET /api/search/cases | Docket search by party, judge, court |
| GET /api/search/opinions | Case law search — add &semantic=true for semantic search |
| GET /api/search/judges | Judge lookup by name |
| GET /api/judge-profile | Single-judge bio + recent assigned dockets |
| GET /api/judge-disclosures | Judge financial disclosures (investments, gifts, debts) |
| GET /api/search/recap | RECAP archive search |
| GET /api/courts | List all federal courts |
| GET /api/case/{id} | Get single case details |
| GET /api/health | Backend health check |
Example Requests
# Search cases by party
curl "http://localhost:8000/api/search/cases?party=Apple&limit=10"
# Search case law (keyword)
curl "http://localhost:8000/api/search/opinions?query=patent&court=cafc&limit=10"
# Search case law (semantic — finds cases by meaning)
curl "http://localhost:8000/api/search/opinions?query=tenant+evicted+for+having+a+dog&semantic=true&limit=10"
# Find judges
curl "http://localhost:8000/api/search/judges?name=Roberts&limit=10"
# Pull a full judge profile in one call
curl "http://localhost:8000/api/judge-profile?name=Tanya+Chutkan&max_cases=25"
# Get a judge's financial disclosures
curl "http://localhost:8000/api/judge-disclosures?name=Chutkan"Response Format
All successful responses return:
{
"status": "success",
"total": 42,
"page": 1,
"count": 20,
"results": [ ... ],
"timestamp": "2024-04-27T14:30:00.000Z"
}All requests require a valid COURTLISTENER_TOKEN. If the token is not set, searches fail with a 503 error.
- Rate limits — CourtListener applies rate limiting. Free accounts have daily request caps. Check their API documentation for current limits.
- Search speed — Large datasets may take several seconds. The interface shows a loading spinner while fetching.
- Backend deploy is manual — Pushing to GitHub auto-deploys the frontend (GitHub Pages) but not the backend API on the GCP VM (see Deployment below).
Architecture
The frontend and backend are deployed separately:
- Frontend (
search.html,readme.html) — hosted on GitHub Pages atsubtxtpress.github.io. Pushing to themainbranch auto-deploys the static files. - Backend (
app.py) — runs on a Google Cloud Compute Engine VM (courtlistenerinstance,us-west1-b) under thesubtxtpressproject. The API is atcourtlistener.subtxtpress.com.
Pushing to main on GitHub auto-deploys the HTML files via GitHub Pages. No extra steps needed for frontend changes.
The VM has no git repo — backend files were copied manually. Pushing to GitHub does not update the API server.
Updating the Backend
# SSH into the VM
gcloud compute ssh courtlistener --zone=us-west1-b --project=subtxtpress
# Backend files live at ~/courtlistener
cd ~/courtlistener
# Copy updated files (e.g. via scp or paste)
# Then restart the server
sudo systemctl restart courtlistener # or however the process is managedTo streamline this, you could initialize a git repo on the VM (git init + add a remote) so future updates are just git pull.
"CourtListener API not initialized" (503)
The COURTLISTENER_TOKEN environment variable is not set. Make sure your .env file exists and contains a valid token, then restart app.py.
CORS Errors in Browser Console
Make sure app.py is running and the API base URL in search.html matches your backend URL (http://localhost:8000 for local dev).
Slow Searches
Query complexity, result set size, and CourtListener server load all affect speed. Try narrowing your search with more specific filters.
| File | Purpose |
|---|---|
| search.html | Interactive web interface |
| app.py | FastAPI backend (auto-loads .env) |
| .env.example | Token template — copy to .env |
| courtlistener_toolkit.py | Core Python client library |
| courtlistener_explorer.py | Alternative CLI tool |