Search the statement by fields the provider cannot filter

Filters the statement by **PIX key, counterparty, amount range, direction and status** — fields the banking provider does not filter server-side. ### Read this before integrating This endpoint is **expensive by construction**. Because the provider cannot filter by these fields, every call walks the statement for the period page by page and applies the filters row by row. A single call may cost dozens of upstream requests and take **considerably longer** than the regular statement. It exists to make one-off investigation and manual reconciliation easy. **Do not abuse it, and never use it for recurring queries or polling.** For continuous tracking of incoming PIX, use [webhooks](/docs/webhooks); for bulk data, use the regular paginated statement or the CSV export. Prefer `GET /v1/accounts/{accountId}/statement` whenever its native filters are enough (period, operation type, order). Reach for this endpoint only when you need a field that only it can filter. ### Pagination is by cursor, not page number There is no page number: an item's position in the filtered result has no fixed relationship to its position in the raw statement, so jumping to an arbitrary page would mean re-walking the period from the start. Each call spends a bounded budget (a maximum number of provider pages and a wall-clock limit). When the budget runs out before the end of the period, the response carries `exhausted: false` and a `nextCursor` — repeat the call passing `cursor=<nextCursor>` to resume exactly where the scan stopped. When `exhausted` is `true`, the period was fully walked and what you received is everything that matches. ### Default order is oldest first; `order=desc` is for "just the end of the day" By default the scan runs in ascending date order and the response echoes `order: "asc"`. This is what makes cursor resumption exact rather than a preference: the cursor is a position in the provider's statement, so in descending order an entry arriving mid-scan would enter at the top and push every later position along — the resumed call would return rows you already received. In ascending order new entries land at the end and nothing already scanned moves. Since the default window is the current day, it almost always includes "now", so this is the common case. `order=desc` exists for accounts with thousands of entries a day that only want the **most recent** ones: the scan starts from the newest and stops as soon as the result page is full. In this mode **`cursor` is refused** (`400 invalid_cursor`) for the reason above. To continue, use time instead of position: when `exhausted` is `false` the response carries `nextOccurredBefore`; pass it as `occurredBefore` on the next call. It is the instant of the last row examined, and the window is inclusive, so rows sharing that same second may come back — deduplicate by `id`. A time boundary does not move when a new entry lands at the top, which is what makes it safe where a cursor is not. Each continuation re-reads from the newest down to the boundary (the provider paginates by position), so `desc` is for the tail of the period; to walk a whole period backwards, use `asc` with a cursor. ### `occurredAfter` / `occurredBefore` narrow by time of day Both are RFC 3339 instants **with an explicit offset** (`-03:00` or `Z`), inclusive on both ends, applied on top of the date window. They only shorten the scan when they are the boundary in the scan direction: `occurredAfter` with `order=desc` and `occurredBefore` with `order=asc` stop the scan the moment the boundary is crossed (`exhausted: true`). In the opposite direction they are just filters — the provider only accepts dates, so the pages before the instant are still read. Typical use: `order=desc&occurredAfter=2026-09-20T17:00:00-03:00` to get everything since 17:00 without walking the morning. A call may legitimately return **zero items with a cursor** (or with `nextOccurredBefore`): it means the budget was spent on rows that did not match, not that there is nothing to find. The cursor is bound to the filter set. Changing any filter invalidates it and the API answers `400 invalid_cursor` — start the search over without a cursor. There is no total count, on purpose: counting would require walking the whole period, which is the very cost this design avoids.