On this page

Cause lists

Hearing listings for the matters in your account, the published list of a court you have a matter in, and a check of the CNRs you watch.

Cause list endpoints

Only listings that were found are reported.

Before you start

Responses report the listings that were found. An empty result is not a statement about whether a matter is listed, so confirm against the court's own list when it matters.
Needs the causelist scope. A key with no explicit scopes carries all of them.
The account that owns the key needs cause list access. Without it every endpoint here answers 403 CAUSE_LISTS_NOT_ENABLED, which is not charged and does not change on retry.
A temporary outage is a 502 UPSTREAM_UNAVAILABLE, not charged. Retry shortly.

GET

/cause-lists/listings

1 credit

Every listing found on a cause list for the matters in your account, within a date range of at most 31 days. Without from and to the range is today and the next 7 days. 1 credit per successful call. limit is capped by your tier's maximum page size and page * limit by its pagination depth; both are refused with a 400, as on search.

Query parameters

Field	Type	Required	Notes
from	string	No	First date of the range, YYYY-MM-DD. Send together with to; omit both for today and the next 7 days.
to	string	No	Last date of the range, YYYY-MM-DD. At most 31 days after from.
page	integer	No	Page number, from 1.
limit	integer	No	Page size, 1 to 100 and no more than your tier's maximum page size. Default 50, or the tier maximum when that is lower.

curl "https://research.courtmesh.ai/api/v1/prod/cause-lists/listings?from=2026-11-05&to=2026-11-12" \
  -H "X-API-Key: cm-YOUR_KEY_HERE"

{
  "success": true,
  "data": [
    {
      "id": "6728a1f0c3d4e5f6a7b8c9d0",
      "matterId": "66f1a2b3c4d5e6f7a8b9c0d1",
      "matterTitle": "Alpha Finance Ltd v. Beta Traders",
      "date": "2026-11-05",
      "courtKey": "DC:99:1:9900001:1:1",
      "court": { "kind": "DC", "name": "District Court, Example City", "courtNo": "1", "judges": ["Sh. A. Example"], "designation": null },
      "item": "1",
      "section": "Urgent Cases",
      "purpose": "REPLY",
      "listType": "civil",
      "caseText": "CMA/1/2024",
      "matchedBy": "cnr",
      "fetchedAt": "2026-11-04T15:30:12.000Z",
      "firstSeenAt": "2026-11-04T15:31:02.000Z"
    }
  ],
  "meta": { "creditsCharged": 1, "metered": true },
  "pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1, "hasMore": false }
}

GET

/matters/:matterId/cause-listings

1 credit

The listings found for one matter in your account, within a date range of at most 31 days. 1 credit per successful call; an unknown matter (404 MATTER_NOT_FOUND) is not charged. The answer carries the matter and its listings, each shaped like a row of GET /cause-lists/listings.

Path and query parameters

Field	Type	Required	Notes
matterId	string	Yes	The 24 character id of the matter.
from	string	No	First date of the range, YYYY-MM-DD. Send together with to; omit both for today and the next 7 days.
to	string	No	Last date of the range, YYYY-MM-DD. At most 31 days after from.

POST

/cause-lists/check

1 credit per CNR readIdempotency-Key

For up to 100 CNRs you watch (see watchlists), reports whether each appears on the cause lists we already hold for a short date range, at most 7 days. Without from and to the range is today and tomorrow, India time. The number of CNRs times the number of dates (both ends included) can be at most 300: with the default 2 dates a call can carry 100 CNRs, and with an 8 date range at most 37. A request never contacts a court: it reads lists stored earlier, so a list for a date may not be there yet. Only a positive listing is claimed.

Request body

Field	Type	Required	Notes
cnrs	string[]	Yes	CNRs to check, 1 to 100. Spacing and case are ignored; repeats are answered once, in the order first sent.
from	string	No	First date, YYYY-MM-DD. Send together with to; omit both for today and tomorrow (India time).
to	string	No	Last date, YYYY-MM-DD. At most 7 days after from.

results[].status and its price

Field	Type	Required	Notes
listed	1 credit	No	A row of this case was found.
no_entry_found	1 credit	No	A list was read (ok or partial) for at least one date and no row of the case was recognised. Not a statement about whether the case is listed; dates[].complete says how much was read.
list_not_read	0 credits	No	We hold no list for those dates yet.
cannot_check	0 credits	No	reason says why, for example pending (the CNR is still being added), record_unavailable, no_case_identity or court_not_supported.
not_watched	0 credits	No	This account does not watch this CNR. Add it to a watchlist first. The answer is the same whether or not anyone else watches it.

Charging

Settled once for the whole call and reported in meta.creditsCharged. The call is refused with 402 when your balance is below the number of watched CNRs in it. If the credits due cannot be settled when the answer is ready, no results are returned: 402 when the wallet no longer covers them, or 503 SETTLEMENT_UNCONFIRMED when the charge could not be confirmed. After that 503, check your balance first: a retry with the same Idempotency-Key is refused with 409 IDEMPOTENCY_IN_PROGRESS for up to 24 hours, and a retry with a new key could charge again.

curl -X POST https://research.courtmesh.ai/api/v1/prod/cause-lists/check \
  -H "X-API-Key: cm-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: listing-check-2026-11-05" \
  -d '{ "cnrs": ["ZZAB010000012024", "ZZAB010000022024"], "from": "2026-11-05", "to": "2026-11-06" }'

{
  "success": true,
  "data": {
    "results": [
      {
        "cnr": "ZZAB010000012024",
        "status": "listed",
        "reason": null,
        "courtKey": "DC:99:1:9900001:1:1",
        "dates": [{ "date": "2026-11-05", "status": "ok", "complete": true, "fetchedAt": "2026-11-04T15:30:12.000Z" }],
        "listings": [{ "date": "2026-11-05", "item": "1", "section": "Urgent Cases", "purpose": "REPLY", "caseText": "CMA/1/2024", "matchedBy": "cnr" }]
      },
      { "cnr": "ZZAB010000022024", "status": "not_watched", "reason": null, "courtKey": null, "dates": [], "listings": [] }
    ],
    "summary": { "listed": 1, "noEntryFound": 0, "listNotRead": 0, "cannotCheck": 0, "notWatched": 1 },
    "from": "2026-11-05",
    "to": "2026-11-06"
  },
  "meta": { "creditsCharged": 1, "metered": true }
}

GET

/cause-lists/court

1 credit with rows, else 0

The published list of one court for one date, for a court you have an open matter in (404 COURT_LIST_NOT_FOUND otherwise, not charged). status says what was read: ok and partial carry rows, and partial means some parts of the list could not be read. none, empty, not_published, invalid_court and unavailable carry no rows and are a 200 that costs 0. The call still needs at least 1 credit available when it starts.

Query parameters

Field	Type	Required	Notes
courtKey	string	Yes	The courtKey returned on a listing: SC, HC:<state>:<bench> or DC:<state>:<district>:<complex>:<establishment>:<court number>, digits only.
date	string	Yes	Date of the list, YYYY-MM-DD.

curl "https://research.courtmesh.ai/api/v1/prod/cause-lists/court?courtKey=DC:99:1:9900001:1:1&date=2026-11-05" \
  -H "X-API-Key: cm-YOUR_KEY_HERE"

Errors

HTTP 400: VALIDATION_ERROR (details lists each field), and on listings also PAGE_LIMIT_EXCEEDED or PAGINATION_DEPTH_EXCEEDED.
HTTP 401: no key, or an unknown or inactive key.
HTTP 402: insufficient balance.
HTTP 403: CAUSE_LISTS_NOT_ENABLED, a key without the causelist scope, or a suspended account; read the code.
HTTP 404: MATTER_NOT_FOUND or COURT_LIST_NOT_FOUND, not charged.
HTTP 429: rate limited, with Retry-After.
HTTP 502: UPSTREAM_UNAVAILABLE, not charged; retry shortly.
HTTP 503: the account standing could not be checked, or (on the check) SETTLEMENT_UNCONFIRMED.

PreviousActs and sections

NextCoverage and reference