> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Court Cases

> Find court decisions and dockets by search words, court, date, case name or docket number.

Search a public archive of published US federal and state court opinions, or choose kind=dockets to search federal cases and their filings. Returns case names, courts, filing dates, citations when available, docket numbers, short excerpts and links, ordered by relevance. For opinions, the filing date is the decision date; for dockets, it is when the case was filed. Coverage varies by court and does not include every case or filing. Only the first page is read, with at most limit matches returned. Docket totals above 2,000 are approximate, with up to 6% error. An excerpt is the start of an opinion or a matching filing, at most 500 characters; it is not a case summary. Open the URL for the source record. The source's terms prohibit using this data for credit, insurance, employment, housing or other eligibility decisions covered by the Fair Credit Reporting Act.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

<ParamField body="query" type="string" required>
  Search words, with quotes for an exact phrase and AND, OR or NOT between terms, for example patent. 1 to 500 characters.
</ParamField>

<ParamField body="kind" type="string">
  opinions searches published federal and state decisions; dockets searches federal cases and their filings. Default opinions. One of `opinions`, `dockets`. Defaults to `"opinions"`.
</ParamField>

<ParamField body="court" type="string">
  Only this court, by its short court ID, for example scotus, cafc or txed.
</ParamField>

<ParamField body="filed_after" type="string">
  Only cases filed on or after this date, YYYY-MM-DD; for opinions, this is the decision date.
</ParamField>

<ParamField body="filed_before" type="string">
  Only cases filed on or before this date, YYYY-MM-DD; for opinions, this is the decision date.
</ParamField>

<ParamField body="case_name" type="string">
  Search within case names, for example Merck. 1 to 200 characters.
</ParamField>

<ParamField body="docket_number" type="string">
  Search within docket numbers, for example 23-1027. 1 to 100 characters.
</ParamField>

<ParamField body="limit" type="integer">
  The most matches to return from the first page, from 1 to 20. Default 10. From 1 to 20. Defaults to `10`.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `record_court_cases_find`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  The public body the data comes from. Always `US federal and state courts (public court records)`.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  When the source says the fact was last updated, or `null` when the source gives no date
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.total" type="integer">
  Matching cases, including those beyond limit; docket counts above 2,000 are approximate.
</ResponseField>

<ResponseField name="data.result.total_is_approximate" type="boolean">
  True for docket counts above 2,000, which may differ by up to 6%.
</ResponseField>

<ResponseField name="data.result.cases" type="object[]">
  Matching cases in relevance order.
</ResponseField>

<ResponseField name="data.result.cases[].case_name" type="string">
  The case name.
</ResponseField>

<ResponseField name="data.result.cases[].court" type="string">
  The court name, or null if absent.
</ResponseField>

<ResponseField name="data.result.cases[].date" type="string">
  Decision date for opinions, case filing date for dockets, YYYY-MM-DD; null if absent.
</ResponseField>

<ResponseField name="data.result.cases[].citation" type="string">
  Citations joined with semicolons, or null if absent.
</ResponseField>

<ResponseField name="data.result.cases[].docket_number" type="string">
  The docket number, or null if absent.
</ResponseField>

<ResponseField name="data.result.cases[].excerpt" type="string">
  Up to 500 characters from an opinion or matching filing, or null if unavailable.
</ResponseField>

<ResponseField name="data.result.cases[].url" type="string">
  The opinion or docket at its source, or null if unavailable.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/find/record-court-cases \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "query": "patent",
      "court": "cafc",
      "case_name": "Merck",
      "docket_number": "23-1027",
      "filed_after": "2025-01-01",
      "filed_before": "2025-12-31",
      "limit": 1
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/find/record-court-cases", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "query": "patent",
      "court": "cafc",
      "case_name": "Merck",
      "docket_number": "23-1027",
      "filed_after": "2025-01-01",
      "filed_before": "2025-12-31",
      "limit": 1
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('find/record-court-cases', {
    query: 'patent',
    court: 'cafc',
    case_name: 'Merck',
    docket_number: '23-1027',
    filed_after: '2025-01-01',
    filed_before: '2025-12-31',
    limit: 1
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "record_court_cases_find",
      "result": {
        "total": 1,
        "total_is_approximate": false,
        "cases": [
          {
            "case_name": "Cqv Co., Ltd. v. Merck Patent Gmbh",
            "court": "Court of Appeals for the Federal Circuit",
            "date": "2025-03-10",
            "citation": "130 F.4th 1344",
            "docket_number": "23-1027",
            "excerpt": "Case: 23-1027 Document: 77 Page: 1 Filed: 03/10/2025 United States Court of Appeals for the Federal Circuit ______________________ CQV CO., LTD., Appellant v. MERCK PATENT GMBH, Appellee ______________________ 2023-1027 ______________________ Appeal from the United States Patent an",
            "url": "https://www.courtlistener.com/opinion/10353022/cqv-co-ltd-v-merck-patent-gmbh/"
          }
        ]
      },
      "evidence": {
        "source": "US federal and state courts (public court records)",
        "source_kind": "public",
        "retrieved_at": "2026-10-14T12:00:00.000Z",
        "as_of": null
      }
    }
  }
  ```
</ResponseExample>

<Info>Price: \$0.01 per lookup. See [Pricing](/pricing) for every tool.</Info>

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.