GET
List batches

Authorizations

Authorization
string
header
required

The caller's access_token from authentication. Management API callers send the id_token. The program and environment come from the token.

Query Parameters

programId
string

Required on the Management API, where the token carries no program: omitting it returns 400. Customer API callers resolve the program from their token and should omit it; a value sent there is ignored.

limit
integer
default:50

Maximum number of batches to return. Values above 200 are clamped to 200: the response is capped, not rejected. Invalid values include 0, negative numbers, non-integer strings, and mixed strings such as 10abc.

Required range: x >= 1
nextToken
string

Pagination token returned by a previous response.

lookbackDays
integer
default:30

Lookback window in days for program-wide Management API listings (a caller with no custodian), used only when date is not provided. Default 30, at most 365. Ignored for customer- and custodian-scoped callers, whose listings are unbounded. A supplied value is still validated even when date takes precedence, so an invalid one is rejected either way. Invalid values include 0, negative numbers, non-integer strings, and mixed strings such as 10abc.

Required range: 1 <= x <= 365
date
string<date>

UTC calendar date filter applied to each batch's createdDateTime. Available on the Customer API and the Management API alike. Use YYYY-MM-DD exactly: empty strings, 2026/06/30, 2026-2-3 and impossible dates such as 2026-02-30 are all rejected. Where it applies, it takes precedence over lookbackDays.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2026-06-30"

drafts
enum<string>

Set to true to list batches awaiting submission instead of submitted ones. Omit it and the response is unchanged. Drafts are held in separate indexes, so this selects a different query rather than filtering the normal one: a draft never appears in the default listing. Only the exact string true enables it.

Available options:
true,
false
includeItemSummary
enum<string>

Set to true to include the per-batch item summary: itemsStatus (counts by item status) and totalAmount (the sum of item amounts). Omit it and both fields are absent. Available to every role, including customer callers. Only the exact string true enables it. Has no effect with drafts=true, which has no item rows to summarise.

Available options:
true,
false

Response

Batches. The example shows a response to ?includeItemSummary=true.

success
boolean
Example:

true

data
object