POST /v2/cases/batch

Overview

POST /v2/cases/batch runs up to 50 case queries in a single HTTP call. One x402 payment covers the entire batch. The payment transaction must be sized for the full batch: $0.99 \u00d7 N queries. Base URL: https://api.docketlayer.ai Price: $0.99 \u00d7 number of queries in the batch Sandbox: Add ?test=1 or X-DocketLayer-Test: 1 \u2014 returns fixture data for all queries, no charge

Request

Content-Type: application/json

{
  "queries": [
    {
      "case_id": "1:24-cv-01234",
      "court_code": "nysd",
      "last_checked": "2026-01-01T00:00:00Z",
      "context": "basic"
    },
    {
      "case_id": "1:22-bk-11068",
      "court_code": "deb",
      "last_checked": "2026-01-01T00:00:00Z"
    }
  ]
}

Query object fields

Field	Type	Required	Description
`case_id`	string	Yes	Case identifier
`court_code`	string	Yes	Court identifier
`last_checked`	string	No	ISO-8601 timestamp. When supplied, result includes a `delta` block.
`context`	string	No	`basic` (default) or `full`
`language`	string	No	`en` or `fr`
`filing_types`	string	No	Comma-separated filing types to filter the delta

Maximum batch size: 50 queries. Requests exceeding 50 return 413.

Response

{
  "meta": {
    "request_id": "req_01jt7y4kx0",
    "queried_at": "2026-04-29T12:00:00Z",
    "batch_size": 2,
    "successful": 2,
    "failed": 0,
    "total_cost_usd": 1.98,
    "sandbox": false,
    "tag": null
  },
  "results": [
    {
      "case_id": "1:24-cv-01234",
      "court_code": "nysd",
      "status": "success",
      "response": {
        "meta": { "...same as GET /v2/case..." },
        "case_id": "1:24-cv-01234",
        "court_code": "nysd",
        "case": { "...case fields..." },
        "delta": { "...delta fields if last_checked supplied..." }
      }
    },
    {
      "case_id": "1:22-bk-11068",
      "court_code": "deb",
      "status": "success",
      "response": { "..." }
    }
  ]
}

Meta fields

Field	Type	Description
`batch_size`	number	Total number of queries submitted
`successful`	number	Number of queries that returned data
`failed`	number	Number of queries that returned errors
`total_cost_usd`	number	Total charge \u2014 `batch_size` \u00d7 $0.99

Result object

Each entry in results has:

Field	Type	Description
`case_id`	string	The case_id from your query
`court_code`	string	The court_code from your query
`status`	string	`success` or `error`
`response`	object	Full case response (same structure as `GET /v2/case`) \u2014 present when `status` is `success`
`error`	object	Error details \u2014 present when `status` is `error`

Error result

{
  "case_id": "9:99-cv-99999",
  "court_code": "nysd",
  "status": "error",
  "error": {
    "code": "case_not_found",
    "message": "Case '9:99-cv-99999' not found in court 'nysd'.",
    "documentation_url": "https://docketlayer.ai/reference/errors#case_not_found"
  }
}

Notes

Payment \u2014 A single x402 payment covers the batch. The payment transaction must be sized for the full batch (batch_size \u00d7 $0.99). If all cases fail, no payment is settled. If some cases fail, the full batch amount is still settled \u2014 x402 payments are atomic and cannot be partially refunded. Ordering \u2014 Results are returned in the same order as your queries array. Callbacks \u2014 The batch endpoint does not support callback_url per-query. Callers needing async callback delivery should use GET /v2/case directly. Rate limiting \u2014 Rate limit is checked once at the batch level. A single batch counts as one request against the per-minute limit, but each successful case counts toward the per-day limit.

Getting started

API reference

Concepts

Guides

Integration quickstarts

Resources

Overview

Request

Query object fields

Response

Meta fields

Result object

Error result

Notes

​Overview

​Request

​Query object fields

​Response

​Meta fields

​Result object

​Error result

​Notes

Overview

Request

Query object fields

Response

Meta fields

Result object

Error result

Notes