courtlistener-guide

Scope

Use CourtListener for US written opinions, citation links, federal RECAP dockets, judge records, oral arguments, and judicial disclosures. A CourtListener API token is required. RECAP is a partial federal PACER mirror; this server does not cover state-court dockets or purchase PACER documents.

Identifiers

• Opinion search and citation lookup return cluster IDs: a decision grouping its opinion variants. Pass these to courtlistener_get_opinion and courtlistener_get_citations.
• Variant IDs and variant cites lists identify individual opinions, not clusters. Do not pass those IDs to tools requiring a cluster ID; use courtlistener_get_citations to follow the authority chain.
• Docket IDs come from docket search or linked opinion records. Use them for courtlistener_get_docket and courtlistener_get_parties. Document IDs, docket-entry IDs, PACER document numbers, and docket numbers are distinct identifiers.
• Judge search returns person IDs; opinion author IDs and oral-argument panel IDs also identify people. Use these for courtlistener_get_judge and judge-specific disclosure searches. Resolve a name before linking records to a person.
• Disclosure search returns disclosure IDs for courtlistener_get_financial_disclosure. Oral-argument search returns audio IDs for courtlistener_get_oral_argument.

Gates

• Inspect each citation lookup result's resolution status. A successful call can contain unresolved citations or several candidate cases; resolve the intended case before following its cluster.
• Read the relevant opinion variant before attributing a holding or characterizing how a later decision treats a precedent. Citation edges establish links, not approval, rejection, or distinguishing treatment. Search snippets are cluster relevance previews and may come from a concurrence or dissent.
• Finish the text needed for the conclusion. An outline is a catalog, not the withheld text. Continue retrieval with the original identity and selection unchanged; reconstruct chunks using their paths and absolute ranges rather than appending repeated rows.
• Keep opinion text and docket backfill retrieval separate. Follow retrieval.next_cursor for the primary opinion and enrichment_retrieval.next_cursor through enrichment_cursor for oversized backfill, with the same cluster and variant selection. Track enrichment ranges independently even when their paths name top-level fields. If enrichment source_id changes, discard prior enrichment slices and collect the replacement; do not discard primary opinion slices merely because backfill changed.
• Check source completion separately from retrieval completion. Exhausting retrieval only exhausts the fetched view: opinion variants, citation source variants, judge positions, or attorney resolution may still be incomplete. Report that limit with the finding.
• Do not stop at an empty page when a continuation remains. Disclosure-year filters and outbound-citation filters can leave an empty page before later matches.
• Do not equate missing RECAP records with a case or filing not existing. Check document availability before relying on a stored copy; do not infer missing content from metadata.
• Select filing text only from documents listed on the same docket entries page. A selection from another page or an entry without explicit matching docket ownership is rejected; list the intended page before retrying.
• Keep filing-text continuation separate from entries pagination. Finish retrieval with the same docket, entries page, and document selection before moving to another entries page. File availability does not establish extracted-text availability: inspect text_status, including unavailable, not_extracted, and unknown outcomes.
• Preserve disclosure dollar ranges as ranges. Check extraction status and retrieve relevant line items before drawing a conclusion from category counts.