Tutorial: Court Listener

Legal

Data source: CourtListener / Free Law Project

Overview

Court Listener wraps CourtListener / Free Law Project, handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-court-listener": {
      "url": "https://context.gnist.ai/mcp/court-listener/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

`search_opinions`

Search US court opinions by keyword, phrase, or party name. Searches 60M+ published federal and state court opinions via CourtListener. Args: query: Search query — keyword, phrase, party name, or legal concept (e.g. "Apple Samsung patent", "qualified immunity", "securities fraud"). Use quotes for exact phrase matching (e.g. '"tortious interference"'). court: Jurisdiction filter — CourtListener court code. Common values: "scotus" (Supreme Court), "ca9" (9th Circuit), "ca2" (2nd Circuit), "cadc" (DC Circuit), "dcd" (DC District), "nysd" (SDNY), "cand" (ND Cal). If omitted, searches all federal and state courts. date_from: Return only opinions filed on or after this date (YYYY-MM-DD). date_to: Return only opinions filed on or before this date (YYYY-MM-DD). limit: Maximum results to return (1–100, default 20). Returns: List of matching opinion clusters with case name, court, date, citation, and text snippet.

Parameter	Type	Required	Description
`query`	string	required	Search query — keyword, phrase, party name, or legal concept (e.g. "Apple Samsung patent", "qualified immunity", "securities fraud"). Use quotes for exact phrase matching (e.g. '"tortious in...
`court`	any	optional	Jurisdiction filter — CourtListener court code. Common values: "scotus" (Supreme Court), "ca9" (9th Circuit), "ca2" (2nd Circuit), "cadc" (DC Circuit), "dcd" (DC District), "nysd" (SDNY...
`date_from`	any	optional	Return only opinions filed on or after this date (YYYY-MM-DD).
`date_to`	any	optional	Return only opinions filed on or before this date (YYYY-MM-DD).
`limit`	integer	optional	Maximum results to return (1–100, default 20). (default: `20`)

curl -X POST "https://context.gnist.ai/mcp/court-listener/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_opinions", "arguments": {"query": "Apple Samsung patent"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/court-listener/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'Apple Samsung patent'},
            'name': 'search_opinions'}},
)
print(resp.json())

`get_opinion`

Retrieve full details for a court opinion cluster by ID. Returns the full opinion text, citation data, judge, and case metadata. Use cluster_id from search_opinions results. Args: cluster_id: CourtListener opinion cluster ID (from search_opinions results). Returns: Full opinion record with case metadata and opinion text (capped at 2000 chars each). Returns an error dict if the opinion is not found.

Parameter	Type	Required	Description
`cluster_id`	integer	required	CourtListener opinion cluster ID (from search_opinions results).

curl -X POST "https://context.gnist.ai/mcp/court-listener/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_opinion", "arguments": {"cluster_id": 5}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/court-listener/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'cluster_id': 5}, 'name': 'get_opinion'}},
)
print(resp.json())

`search_dockets`

Search court dockets by party name to find litigation history. Searches PACER/RECAP dockets for cases where a named entity appears as a party. Useful for due diligence: mapping a company's full litigation history. Args: party_name: Party name to search for — company, person, or organization (e.g. "Theranos", "Elizabeth Holmes", "Meta Platforms"). Exact phrase matching is applied automatically. court: Jurisdiction filter — CourtListener court code (e.g. "ca9", "nysd"). If omitted, searches all courts. year_from: Include only cases filed in this year or later. year_to: Include only cases filed in this year or earlier. limit: Maximum results to return (1–100, default 20). Returns: List of matching dockets with case name, court, date, docket number, and cause.

Parameter	Type	Required	Description
`party_name`	string	required	Party name to search for — company, person, or organization (e.g. "Theranos", "Elizabeth Holmes", "Meta Platforms"). Exact phrase matching is applied automatically.
`court`	any	optional	Jurisdiction filter — CourtListener court code (e.g. "ca9", "nysd"). If omitted, searches all courts.
`year_from`	any	optional	Include only cases filed in this year or later.
`year_to`	any	optional	Include only cases filed in this year or earlier.
`limit`	integer	optional	Maximum results to return (1–100, default 20). (default: `20`)

curl -X POST "https://context.gnist.ai/mcp/court-listener/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_dockets", "arguments": {"party_name": "Theranos"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/court-listener/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'party_name': 'Theranos'}, 'name': 'search_dockets'}},
)
print(resp.json())

`get_docket`

Retrieve full details for a court docket by ID. Returns case metadata, parties (plaintiffs and defendants), and filing info. Use docket_id from search_dockets results. Args: docket_id: CourtListener docket ID (from search_dockets results). Returns: Full docket record with parties, cause, nature of suit, and key dates. Returns an error dict if the docket is not found.

Parameter	Type	Required	Description
`docket_id`	integer	required	CourtListener docket ID (from search_dockets results).

curl -X POST "https://context.gnist.ai/mcp/court-listener/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_docket", "arguments": {"docket_id": 5}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/court-listener/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'docket_id': 5}, 'name': 'get_docket'}},
)
print(resp.json())

`get_citations`

Retrieve the citation graph for a court opinion. Returns two lists: - cites: opinions that this opinion cites (precedents relied upon) - cited_by: opinions that later cite this opinion (subsequent authority) Use cluster_id from search_opinions results. Results are capped at 50 per direction. Args: cluster_id: CourtListener opinion cluster ID. Returns: Citation graph with outbound (cites) and inbound (cited_by) opinion references.

Parameter	Type	Required	Description
`cluster_id`	integer	required	CourtListener opinion cluster ID.

curl -X POST "https://context.gnist.ai/mcp/court-listener/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_citations", "arguments": {"cluster_id": 5}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/court-listener/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'cluster_id': 5}, 'name': 'get_citations'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/court-listener/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/court-listener/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_opinions to find items, then get_opinion to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

Date range filtering
Use date range parameters to narrow results to a specific time window. Dates are typically in YYYY-MM-DD format.

FAQ

What data does Court Listener provide?

U.S. court opinions, oral arguments, and judicial records. It exposes 6 tools: search_opinions, get_opinion, search_dockets, get_docket, get_citations, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Court Listener API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.