> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.docs.relayfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# list_transactions — Filtered, paginated transaction list

> Reference for the list_transactions MCP tool. Query transactions by account, status, direction, date range, and search text with cursor-based pagination.

The `list_transactions` tool returns a filtered, paginated list of transactions for a single organization. Use it to build ledgers, reconcile activity, or search for specific payments. Every request must include `intent` and `organizationId`, and the token must carry the `transactions.read` scope. Results include cursor-based pagination.

## Scope

Required OAuth scope: `transactions.read`

## Input

**organizationId** `string` *required*

The organization to query. Must be one of the organizations the token can access.

**accountId** `string`

Filter to a single account.

**cardId** `string`

Filter to a single card. When combined with `accountId`, both filters must match.

**status** `string`

Filter by transaction status. Allowed values: `created`, `processing`, `settled`, `returned`, `canceled`, `pending`, `unknown`.

**direction** `string`

Filter by direction. Allowed values: `debit`, `credit`.

**search** `string`

Free-text search across transaction fields. Must be 1 to 250 characters.

**occurredAfter** `string`

Inclusive lower bound. Accepts RFC 3339 timestamp or `YYYY-MM-DD`.

**occurredBefore** `string`

Inclusive upper bound. Accepts RFC 3339 timestamp or `YYYY-MM-DD`. When a date-only value is provided, the upper bound is the end of that day. The date window is rejected if inverted (after > before).

**cursor** `string`

Opaque pagination cursor from a previous response. Keep the same `pageSize` and filters when following cursors. Never parse, edit, or reuse a cursor across different filter sets.

**pageSize** `integer` (default: 50)

Number of results per page. Must be between 1 and 100.

**intent** `string` *required*

What the user asked for and why this call serves it, in 1 to 500 characters. Required on every tool call. See [Common tool arguments](https://mcp.docs.relayfi.com/concepts/transport.md#common-tool-arguments).

## Output

**data** `Transaction[]` *required*

Array of transactions matching the filters.

**Transaction**

**object** `string` *required*

Always `"transaction"`.

**id** `string` *required*

Unique transaction identifier.

**organizationId** `string` *required*

Organization the transaction belongs to.

**accountId** `string` *required*

Account the transaction belongs to.

**cardId** `string | null` *required*

Card associated with the transaction, if any.

**amount** `Money` *required*

Unsigned amount as a [Money](https://mcp.docs.relayfi.com/concepts/results.md#money) object. Use `direction` for the sign.

**currency** `string` *required*

Always `"USD"`.

**direction** `string` *required*

Sign carrier for the amount. Values: `debit`, `credit`.

**status** `string` *required*

Transaction lifecycle status. Values: `created`, `processing`, `settled`, `returned`, `canceled`, `pending`, `unknown`.

**type** `string` *required*

Payment rail. Values: `ach`, `wire`, `card`, `check`, `transfer`, `fee`, `interest`, `other`.

**description** `string` *required*

Human-readable description.

**counterpartyName** `string` *required*

Name of the counterparty.

**counterpartyCategory** `string` *required*

Category of the counterparty.

**occurredAt** `string` *required*

Timestamp when the transaction occurred, in RFC 3339 format.

**pagination** `object` *required*

Cursor-based pagination metadata.

**Pagination**

**hasNextPage** `boolean` *required*

Whether more results are available.

**pageSize** `integer` *required*

Number of results in this page.

**nextCursor** `string`

Opaque cursor to fetch the next page. Present only when `hasNextPage` is `true`.

## Example

```json Request theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_transactions",
    "arguments": {
      "intent": "User asked for July debits on the Operating account; listing settled debits for that month.",
      "organizationId": "org_1",
      "accountId": "acc_1",
      "status": "settled",
      "direction": "debit",
      "occurredAfter": "2026-07-01",
      "occurredBefore": "2026-07-31",
      "pageSize": 10
    }
  }
}
```

```json Response theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "data": [
        {
          "object": "transaction",
          "id": "txn_1",
          "organizationId": "org_1",
          "accountId": "acc_1",
          "cardId": null,
          "amount": { "cents": 12500, "display": "125.00", "currency": "USD" },
          "currency": "USD",
          "direction": "debit",
          "status": "settled",
          "type": "card",
          "description": "Coffee",
          "counterpartyName": "Blue Bottle",
          "counterpartyCategory": "restaurants",
          "occurredAt": "2026-07-01T14:03:00.000Z"
        }
      ],
      "pagination": {
        "hasNextPage": false,
        "pageSize": 10
      }
    }
  }
}
```

## Notes

* Follow `nextCursor` until `hasNextPage` is `false`. Keep the same `pageSize` and filters on every page.
* Cursors are opaque and bound to the filter set. Never parse, edit, or reuse a cursor across different filters.
* If an invalid cursor is supplied, the tool returns an MCP error: `The pagination cursor is invalid. Restart pagination without a cursor and keep the same pageSize for subsequent pages.`

> [card] [get\_transaction](https://mcp.docs.relayfi.com/tools/get-transaction.md)
>
> Fetch a single transaction by ID.

> [card] [Result conventions](https://mcp.docs.relayfi.com/concepts/results.md)
>
> Learn how pagination and dual-channel output work across all tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.