Get Bulk Transactions

Returns transactions across your connected users as a single flat, keyset-paginated list, newest first. Every row carries the externalReferenceId and accountId of the user it belongs to. There is no per-user cap — page with nextCursor to walk every transaction in the window across every target user. Defaults to the last 90 days when no date filter is supplied.

Breaking change. This query previously returned results, one entry per target user, each holding up to 20 transactions. It now returns a flat transactions list with cursor pagination. See Migrating from the per-target response.

Requirements

Authorization: Basic <API_KEY> (your application API key)
The bulk API capability on your application
The LIST_PAYMENT and LIST_PURCHASES scopes on each target user’s grant

Failures are reported per target and never fail the whole request. See Bulk API Overview for the targeting model and error codes.

Query

query GetBulkTransactions(
  $targetSpec: BulkTargetSpecInput!
  $createdGte: DateTime
  $createdLte: DateTime
  $includeMetadata: Boolean
  $limit: Int
  $after: String
  $includeTotalCount: Boolean
) {
  getBulkTransactions(
    targetSpec: $targetSpec
    createdGte: $createdGte
    createdLte: $createdLte
    includeMetadata: $includeMetadata
    limit: $limit
    after: $after
    includeTotalCount: $includeTotalCount
  ) {
    transactions {
      externalReferenceId
      accountId
      recordId
      transactionType
      amount
      status
      createdAt
      memo
      transactionCategory
    }
    errors {
      externalReferenceId
      accountId
      code
      message
    }
    totalCount
    targetCount
    succeededTargetCount
    failedTargetCount
    nextCursor
    hasMore
  }
}

Variables

{
  "targetSpec": { "mode": "SELECTED", "targets": ["your-user-001", "your-user-002"] },
  "createdGte": null,
  "createdLte": null,
  "includeMetadata": false,
  "limit": 100,
  "after": null,
  "includeTotalCount": true
}

Response

{
  "data": {
    "getBulkTransactions": {
      "transactions": [
        {
          "externalReferenceId": "your-user-001",
          "accountId": "8f3c…",
          "recordId": "f85b1ce1-1766-4af5-b539-7f3fab4db33d",
          "transactionType": "Account Transfer - In",
          "amount": 25.0,
          "status": "SETTLED",
          "createdAt": "2026-07-01T00:00:00.000Z",
          "memo": null,
          "transactionCategory": null
        },
        {
          "externalReferenceId": "your-user-001",
          "accountId": "8f3c…",
          "recordId": "ede29c85-6d9c-4a7e-b2be-9b6ec7b93cb5",
          "transactionType": "Add Money",
          "amount": 100.0,
          "status": "SETTLED",
          "createdAt": "2026-06-30T18:12:04.000Z",
          "memo": null,
          "transactionCategory": null
        }
      ],
      "errors": [
        {
          "externalReferenceId": "your-user-002",
          "accountId": null,
          "code": "TARGET_NOT_CONNECTED",
          "message": "The id does not correspond to a user currently connected to your application."
        }
      ],
      "totalCount": 1284,
      "targetCount": 2,
      "succeededTargetCount": 1,
      "failedTargetCount": 1,
      "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2…",
      "hasMore": true
    }
  }
}

Arguments

Argument	Type	Description
`targetSpec`	`BulkTargetSpecInput!`	Target selection. See Targeting.
`createdGte`	`DateTime`	Only include transactions created at/after this time. Defaults to 90 days before `createdLte`. Must not be after `createdLte`.
`createdLte`	`DateTime`	Only include transactions created at/before this time. Defaults to now.
`includeMetadata`	`Boolean`	Also return `memo` and `transactionCategory`. Slower; defaults to `false`.
`limit`	`Int`	Maximum transactions in this page. Default and maximum are both `100`. Larger values are clamped, not rejected.
`after`	`String`	Opaque cursor from a previous response’s `nextCursor`. Omit for the first page.
`includeTotalCount`	`Boolean`	Also return `totalCount`. Costs a second scan of the window, so it defaults to `false`. Prefer `hasMore`/`nextCursor` to drive paging.

The date window bounds the data; limit bounds a single page. The window may span at most 365 days. Transactions are stored in monthly partitions and each partition in the window is scanned per target, so a wider window costs more per page — it isn’t free. For longer history, use the export.

Targeting

targetSpec.mode is either SELECTED (name the users in targets, using the externalReferenceId you connected them with) or ALL_CONNECTED (every user with an active grant on your application). Duplicate targets are removed. This query accepts up to 1,000 target users. For more than that, use the asynchronous export.

Response fields

Field	Type	Description
`transactions`	`[BulkTransaction!]!`	This page of transactions across all target users, newest first, each attributed to its user.
`errors`	`[BulkTargetFailure!]!`	Targets that were skipped or failed. First page only (empty on subsequent pages), and capped at a sample of 100 so a large sweep can’t return a huge payload. Use `failedTargetCount` for the true total.
`totalCount`	`Int`	Total transactions matching the request across all pages — every target, whole window. Opt-in via `includeTotalCount`, and only ever computed on the first page; `null` otherwise. It costs a second scan of the window, so ask for it only when you need to show a total.
`targetCount`	`Int!`	Number of target users addressed by the request.
`succeededTargetCount`	`Int!`	Number of target users this request was authorized to read — resolved, and holding the required scopes. Independent of this page’s contents: an authorized user with no transactions in the window still counts.
`failedTargetCount`	`Int!`	Number of target users that could not be read. Returned on every page (unlike `errors`), and the true total even when `errors` is truncated to its 100-item sample.
`nextCursor`	`String`	Opaque cursor for the next page; `null` when this is the last page. Keyset-based, so it’s stable across concurrent writes.
`hasMore`	`Boolean!`	Whether more transactions remain beyond this page.

`BulkTransaction`

Field	Type	Description
`externalReferenceId`	`String`	Your reference id for the user this transaction belongs to.
`accountId`	`UUID!`	The Fluz account id of the user this transaction belongs to.
`recordId`	`UUID`	Unique identifier for the transaction record.
`transactionType`	`String`	Display-style label, e.g. `"Account Transfer - In"`, `"Account Transfer - Out"`, `"Spend Account Transfer - In"`, `"Add Money"`. Not an enum — see the note below.
`amount`	`Float!`	The transaction amount.
`status`	`TransactionStatus`	`PENDING` or `SETTLED`.
`createdAt`	`DateTime`	When the transaction was created.
`memo`	`String`	Populated only when `includeMetadata: true`.
`transactionCategory`	`String`	Populated only when `includeMetadata: true`.

Four behaviors to be aware of:

transactionType is a human-readable label, not a stable enum — values look like "Account Transfer - In" or "Add Money", not TRANSFER or DEPOSIT. The set is open and the wording may change. Don’t switch on it in code; use recordId and the amount/sign for logic, and treat this field as display text.
Only PENDING and SETTLED transactions are returned — declined and other non-baseline records are excluded, matching the single-user transactions surface.
Ordering is newest first across the whole flat stream (createdAt descending, ties broken by recordId, then by user).
A transaction on a shared account appears once per grant that can see it — two attributed rows with the same recordId and different externalReferenceId.

BulkTransaction is a purpose-built, narrow type. It is not the full Transaction type returned by the single-user transactions query — the fields above are the complete set. For richer per-transaction data, use the asynchronous export.

`BulkTargetFailure`

Field	Type	Description
`externalReferenceId`	`String`	Your reference id for the target, when available.
`accountId`	`UUID`	The target’s account id, when the target was resolved.
`code`	`String!`	Machine-readable failure reason (see below).
`message`	`String!`	Human-readable failure detail.

`code`	Meaning
`TARGET_NOT_CONNECTED`	The id is not a user currently connected to your application.
`INVALID_TARGET_IDENTIFIER`	The id is not a valid identifier.
`INSUFFICIENT_SCOPE`	The user’s grant is missing `LIST_PAYMENT` and/or `LIST_PURCHASES`.
`ACCOUNT_NOT_PERMITTED`	The grant does not permit this operation on the requested spend account.

A failed target never fails the request. Select both identifiers. externalReferenceId is null for any grant you connected without one, so on its own it may not tell you which user failed. accountId is populated whenever the target resolved — which is the case for INSUFFICIENT_SCOPE and ACCOUNT_NOT_PERMITTED — and is null only for TARGET_NOT_CONNECTED and INVALID_TARGET_IDENTIFIER, where nothing resolved. Querying errors { externalReferenceId accountId code message } means every entry is identifiable by at least one of the two.

Request-level errors

Everything above is per-target. These reject the whole request, returning data.getBulkTransactions: null plus a GraphQL error. Branch on extensions.code, never on the message text — wording can change, codes won’t.

Condition	`extensions.code`	`extensions.errorName`	`statusCode`
Window wider than 365 days	`APPLICATIONS-0009`	`InvalidDateWindow`	422
`createdGte` after `createdLte`	`APPLICATIONS-0009`	`InvalidDateWindow`	422
Malformed or tampered `after` cursor	`APPLICATIONS-0010`	`InvalidPaginationCursor`	422
No eligible targets — none connected, or none with the required scopes	`APPLICATIONS-0011`	`InvalidBulkRequest`	422
Malformed request payload (bad `targetSpec`, empty `targets`)	`APPLICATIONS-0011`	`InvalidBulkRequest`	422
More than 1,000 target users	`APPLICATIONS-0008`	`TargetLimitExceeded`	422
Bulk API not enabled for your application	`APPLICATIONS-0003`	`BulkApiAccessDenied`	403
Missing credentials, or a non-Basic scheme	`AUTH-0002`	`InvalidCredentials`	401

The two date failures share a code — both mean “the range you asked for isn’t usable” — and the message distinguishes them:

{
  "errors": [
    {
      "message": "The requested window exceeds the 365-day maximum. Narrow the range, or use the asynchronous transactions export for a wider pull.",
      "path": ["getBulkTransactions"],
      "extensions": {
        "errorName": "InvalidDateWindow",
        "code": "APPLICATIONS-0009",
        "statusCode": 422,
        "userFriendly": true
      }
    }
  ],
  "data": { "getBulkTransactions": null }
}

A cursor altered in any way — truncated, re-encoded, hand-edited — fails as APPLICATIONS-0010 before it reaches the database. Treat it as “start again from page one”, not as retryable.

Paging

Read the first page, then follow nextCursor until hasMore is false. Keep every other argument identical across pages — the cursor encodes a position in that specific query’s ordering.

# Page 1: omit `after`. Read errors here — they are first-page only. Ask for totalCount only
# if you actually need it; it costs an extra scan.
{
  getBulkTransactions(targetSpec: { mode: ALL_CONNECTED }, limit: 100, includeTotalCount: true) {
    transactions { recordId externalReferenceId amount createdAt }
    errors { externalReferenceId accountId code message }
    totalCount
    failedTargetCount
    nextCursor
    hasMore
  }
}

# Page 2+: pass the previous nextCursor.
{
  getBulkTransactions(
    targetSpec: { mode: ALL_CONNECTED }
    limit: 100
    after: "eyJjcmVhdGVkQXQiOiIyMDI2LTA2…"
  ) {
    transactions { recordId externalReferenceId amount createdAt }
    nextCursor
    hasMore
  }
}

Because paging is keyset-based rather than offset-based, transactions written while you page won’t shift rows across page boundaries or produce duplicates.

Migrating from the per-target response

Before	Now
`results[]`, one entry per target user	`transactions[]`, one entry per transaction. Group client-side by `externalReferenceId` to rebuild the old shape.
`results[].transactions` (full `Transaction`)	Top-level `transactions` of the narrower `BulkTransaction` type.
`results[].error`	`errors[]` — a flat list of failed targets, first page only, capped at a 100-item sample.
`results[].totalCount` (per target)	`totalCount` (request-wide, opt-in via `includeTotalCount`, first page only). Per-target totals are no longer returned.
`results[].hasNextPage` (per target)	`hasMore` + `nextCursor` (request-wide keyset paging).
`successCount` / `failureCount`	`succeededTargetCount` / `failedTargetCount`.
20 transactions per target, hard cap	No per-user cap. `limit` (default and max 100) bounds the page.
90-day window was a hard cap	90 days is now the default; the hard cap is 365 days.
100 target users, hard cap	1,000 target users.

When to use the export instead

getBulkTransactions can walk complete history by paging, so the export is for pulls you’d rather not page through — more than 1,000 users, windows longer than a year, scheduled batch jobs, or when you need richer per-transaction fields than BulkTransaction carries. Submit GET_TRANSACTIONS_EXPORT via submitBulkOperation, poll getBulkOperationJob, and download the NDJSON from the short-lived resultUrl. See Bulk Operations.

​Requirements

​Query

​Variables

​Response

​Arguments

​Targeting

​Response fields

​BulkTransaction

​BulkTargetFailure

​Request-level errors

​Paging

​Migrating from the per-target response

​When to use the export instead

Requirements

Query

Variables

Response

Arguments

Targeting

Response fields

`BulkTransaction`

`BulkTargetFailure`

Request-level errors

Paging

Migrating from the per-target response

When to use the export instead