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

# Docket Search

> Search federal court dockets and filings

Search federal court dockets or retrieve a specific docket with optional filing entries. Covers all federal district and appellate courts. Use `legal.listCourts()` to resolve court slugs for filtering.

## Search dockets

```bash title="Endpoint" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /legal/v1/docket
```

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl -X POST https://api.case.dev/legal/v1/docket \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "search",
      "query": "Apple v. Samsung",
      "court": "cand",
      "dateFiledAfter": "2020-01-01",
      "limit": 10
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev legal:v1 docket
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  const results = await client.legal.docket({
    type: 'search',
    query: 'Apple v. Samsung',
    court: 'cand',                // Northern District of California
    dateFiledAfter: '2020-01-01',
    limit: 10,
  });

  console.log(`Found ${results.found} dockets`);

  for (const docket of results.dockets) {
    console.log(`${docket.caseName} (${docket.docketNumber})`);
    console.log(`  Court: ${docket.court}`);
    console.log(`  Filed: ${docket.dateFiled}`);
  }
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  results = client.legal.v1.docket(
      type='search',
      query='Apple v. Samsung',
      court='cand',
      date_filed_after='2020-01-01',
      limit=10,
  )

  print(f'Found {results.found} dockets')

  for docket in results.dockets:
      print(f'{docket.case_name} ({docket.docket_number})')
      print(f'  Court: {docket.court}')
      print(f'  Filed: {docket.date_filed}')
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  response, _ := client.Legal.V1.Docket(ctx)
  fmt.Println(response)
  ```
</CodeGroup>

## Look up a docket

Retrieve a specific docket by ID.

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl -X POST https://api.case.dev/legal/v1/docket \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "lookup",
      "docketId": "4214664"
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev legal:v1 docket
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  const docket = await client.legal.docket({
    type: 'lookup',
    docketId: '4214664',
  });

  console.log(`${docket.docket.caseName}`);
  console.log(`Court: ${docket.docket.court}`);
  console.log(`Assigned to: ${docket.docket.assignedTo}`);
  console.log(`Filed: ${docket.docket.dateFiled}`);
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  docket = client.legal.v1.docket(
      type='lookup',
      docket_id='4214664',
  )

  print(docket.docket.case_name)
  print(f'Court: {docket.docket.court}')
  print(f'Assigned to: {docket.docket.assigned_to}')
  print(f'Filed: {docket.docket.date_filed}')
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  response, _ := client.Legal.V1.Docket(ctx)
  fmt.Println(response)
  ```
</CodeGroup>

## Look up docket entries

Pass `includeEntries: true` in lookup mode to return the docket plus filing entries and attached RECAP document metadata.

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl -X POST https://api.case.dev/legal/v1/docket \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "lookup",
      "docketId": "4214664",
      "includeEntries": true,
      "limit": 10,
      "offset": 0
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev legal:v1 docket \
    --type lookup \
    --docket-id 4214664 \
    --include-entries \
    --limit 10 \
    --offset 0
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  const docket = await client.legal.docket({
    type: 'lookup',
    docketId: '4214664',
    includeEntries: true,
    limit: 10,
    offset: 0,
  });

  for (const entry of docket.entries ?? []) {
    console.log(`#${entry.entryNumber ?? 'n/a'} ${entry.date}: ${entry.description}`);

    for (const document of entry.documents) {
      console.log(`  Document ${document.documentNumber}: ${document.pdfUrl ?? 'not available'}`);
    }
  }
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  docket = client.legal.v1.docket(
      type='lookup',
      docket_id='4214664',
      include_entries=True,
      limit=10,
      offset=0,
  )

  for entry in docket.entries or []:
      print(f'#{entry.entry_number or "n/a"} {entry.date}: {entry.description}')

      for document in entry.documents:
          print(f'  Document {document.document_number}: {document.pdf_url or "not available"}')
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  docket, _ := client.Legal.V1.Docket(ctx, casedev.LegalV1DocketParams{
      Type:           casedev.F(casedev.LegalV1DocketParamsTypeLookup),
      DocketID:       casedev.F("4214664"),
      IncludeEntries: casedev.F(true),
      Limit:          casedev.F(int64(10)),
      Offset:         casedev.F(int64(0)),
  })

  for _, entry := range docket.Entries {
      fmt.Printf("#%v %s: %s\n", entry.EntryNumber, entry.Date, entry.Description)
  }
  ```
</CodeGroup>

## Live PACER fetch

For dockets not yet in the RECAP archive, you can trigger a live fetch from PACER. This purchases fresh docket data using CaseMark's PACER account and ingests it into the RECAP archive.

<Warning>
  Live PACER fetches incur PACER fees of up to **\$3.00 per docket sheet**, plus a **\$0.05 service fee**. You must pass `acknowledgePacerFees: true` to confirm you accept these charges.
</Warning>

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl -X POST https://api.case.dev/legal/v1/docket \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "lookup",
      "docketId": "4214664",
      "live": true,
      "acknowledgePacerFees": true
    }'
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  const docket = await client.legal.docket({
    type: 'lookup',
    docketId: '4214664',
    live: true,
    acknowledgePacerFees: true,
  });

  console.log(`Fetched: ${docket.docket.caseName}`);
  console.log(`PACER fees: up to $${docket.pacerFees.maxPacerCost} + $${docket.pacerFees.serviceFee} service fee`);
  console.log(`Fetch took ${docket.pacerFees.fetchDurationMs}ms`);
  ```
</CodeGroup>

### How it works

1. The endpoint first tries to fetch the docket from the free RECAP archive
2. If `live: true`, it triggers a live PACER purchase to fetch fresh docket data
3. CaseMark's PACER account is used -- you don't need your own PACER credentials
4. The fetch typically takes 5-30 seconds depending on docket size
5. Once fetched, the docket is added to the RECAP archive and freely available for future lookups

### Cost and guardrails

| Item              | Cost                                        |
| ----------------- | ------------------------------------------- |
| Service fee       | \$0.05 per request                          |
| PACER fee         | Up to \$3.00 per docket sheet (PACER's cap) |
| **Maximum total** | **\$3.05 per fetch**                        |

Additional guardrails:

* **Daily spend cap**: \$25/day per organization (resets at midnight UTC)
* **Fee acknowledgment required**: Requests without `acknowledgePacerFees: true` return 400
* **Free tier users**: The standard \$10 free credit limit applies -- live fetches count toward it

### Live fetch response

When `live: true`, the response includes a `pacerFees` object:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "type": "lookup",
  "live": true,
  "docket": { ... },
  "pacerFees": {
    "serviceFee": 0.05,
    "maxPacerCost": 3.00,
    "currency": "USD",
    "fetchDurationMs": 12500
  }
}
```

## Resolve court IDs

Court slugs like `cand`, `nysd`, `ca9` identify specific courts. Use `legal.listCourts()` to search for the correct slug to pass as the `court` parameter in `legal.docket()`.

```bash title="Endpoint" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /legal/v1/courts
```

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl -X POST https://api.case.dev/legal/v1/courts \
    -H "Authorization: Bearer $CASEDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "northern district california",
      "jurisdiction": "FD"
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev legal:v1 courts
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  const courts = await client.legal.listCourts({
    query: 'northern district california',
    jurisdiction: 'FD',  // Federal District
  });

  for (const court of courts.courts) {
    console.log(`${court.name} → ${court.id}`);
    // "U.S. District Court for the Northern District of California → cand"
  }
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  courts = client.legal.v1.list_courts(
      query='northern district california',
      jurisdiction='FD',
  )

  for court in courts.courts:
      print(f'{court.name} → {court.id}')
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  response, _ := client.Legal.V1.ListCourts(ctx)
  fmt.Println(response)
  ```
</CodeGroup>

### Jurisdiction codes

| Code | Jurisdiction                     |
| ---- | -------------------------------- |
| `F`  | Federal (all)                    |
| `FD` | Federal District                 |
| `FB` | Federal Bankruptcy               |
| `FA` | Federal Appellate                |
| `FS` | Federal Special (e.g. Tax Court) |
| `S`  | State (all)                      |
| `SA` | State Appellate                  |
| `SS` | State Supreme                    |

## Parameters

### Docket search

| Parameter         | Type       | Required | Description                                                              |
| ----------------- | ---------- | -------- | ------------------------------------------------------------------------ |
| `type`            | `'search'` | Yes      | Search mode                                                              |
| `query`           | `string`   | Yes      | Case name or party name (2-500 chars)                                    |
| `court`           | `string`   | No       | Court slug (e.g. `cand`, `ca9`). Use `legal.listCourts()` to find slugs. |
| `dateFiledAfter`  | `string`   | No       | Lower bound filing date (YYYY-MM-DD)                                     |
| `dateFiledBefore` | `string`   | No       | Upper bound filing date (YYYY-MM-DD)                                     |
| `limit`           | `integer`  | No       | Page size (1-100, default 25)                                            |
| `offset`          | `integer`  | No       | Pagination offset (default 0)                                            |

### Docket lookup

| Parameter              | Type       | Required | Description                                                 |
| ---------------------- | ---------- | -------- | ----------------------------------------------------------- |
| `type`                 | `'lookup'` | Yes      | Lookup mode                                                 |
| `docketId`             | `string`   | Yes      | Docket ID                                                   |
| `includeEntries`       | `boolean`  | No       | Include docket entries/filings (default false).             |
| `live`                 | `boolean`  | No       | Trigger live PACER fetch (default false)                    |
| `acknowledgePacerFees` | `boolean`  | No       | Required when `live: true` -- confirms PACER fee acceptance |
| `limit`                | `integer`  | No       | Entries page size (1-100, default 25)                       |
| `offset`               | `integer`  | No       | Entries pagination offset (default 0)                       |

### Courts lookup

| Parameter      | Type      | Required | Description                                 |
| -------------- | --------- | -------- | ------------------------------------------- |
| `query`        | `string`  | No       | Search court name (min 2 chars)             |
| `jurisdiction` | `string`  | No       | Filter by jurisdiction code                 |
| `inUseOnly`    | `boolean` | No       | Only courts with docket data (default true) |
| `limit`        | `integer` | No       | Page size (1-100, default 50)               |
| `offset`       | `integer` | No       | Pagination offset (default 0)               |

## Response fields

### Docket object

| Field            | Type             | Description                                                |
| ---------------- | ---------------- | ---------------------------------------------------------- |
| `id`             | `string`         | Docket ID                                                  |
| `caseName`       | `string`         | Full case name                                             |
| `docketNumber`   | `string`         | Court docket number (e.g. `5:11-cv-01846`)                 |
| `court`          | `string`         | Full court name                                            |
| `courtId`        | `string`         | Court slug                                                 |
| `dateFiled`      | `string`         | Filing date                                                |
| `dateTerminated` | `string \| null` | Termination date                                           |
| `cause`          | `string \| null` | Cause of action (e.g. `35 U.S.C. 271 Patent Infringement`) |
| `natureOfSuit`   | `string \| null` | Nature of suit classification                              |
| `parties`        | `string[]`       | Party names                                                |
| `assignedTo`     | `string \| null` | Assigned judge                                             |
| `url`            | `string`         | Docket detail URL                                          |
| `pacerCaseId`    | `string \| null` | PACER case ID                                              |

### Docket entry

| Field         | Type      | Description                                        |
| ------------- | --------- | -------------------------------------------------- |
| `entryNumber` | `integer` | Filing number on the docket                        |
| `date`        | `string`  | Filing date                                        |
| `description` | `string`  | Docket text (e.g. "COMPLAINT filed by Apple Inc.") |
| `documents`   | `array`   | Attached RECAP documents                           |

### Document

| Field              | Type              | Description                                               |
| ------------------ | ----------------- | --------------------------------------------------------- |
| `id`               | `string`          | Document ID                                               |
| `documentNumber`   | `string`          | Document number                                           |
| `attachmentNumber` | `integer \| null` | Attachment number (null for main document)                |
| `description`      | `string`          | Document description                                      |
| `pdfUrl`           | `string \| null`  | PDF download URL (if available in RECAP)                  |
| `pageCount`        | `integer \| null` | Number of pages                                           |
| `isAvailable`      | `boolean`         | `true` = free via RECAP archive, `false` = requires PACER |

## Pricing

| Method               | Price |
| -------------------- | ----- |
| `legal.docket()`     | Free  |
| `legal.listCourts()` | Free  |

## Data source

All docket data comes from [CourtListener's RECAP archive](https://free.law/recap/), which aggregates federal court filings contributed by the RECAP browser extension. Coverage includes:

* All federal district courts
* All federal appellate courts
* Federal bankruptcy courts
* Specialty courts (Tax Court, Court of Federal Claims, etc.)

RECAP coverage varies by court and case. High-profile cases and active litigation tend to have the most complete filing histories.