> ## 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_cards — Paginated cards for an organization

> Reference for the list_cards MCP tool. List physical and virtual cards with spending limits, status, and expiration details using cursor-based pagination.

The `list_cards` tool returns a paginated list of cards for a single organization, including physical and virtual cards in any status. Use it to let your agent discover cards, check spending limits, and review expiration dates. The token must carry the `cards.read` scope and every request must include `intent` and `organizationId`.

## Scope

Required OAuth scope: `cards.read`

## Input

**organizationId** `string` *required*

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

**cursor** `string`

Opaque pagination cursor from a previous response. Keep the same `pageSize` 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** `Card[]` *required*

Array of cards.

**Card**

**object** `string` *required*

Always `"card"`.

**id** `string` *required*

Unique card identifier.

**organizationId** `string` *required*

Organization the card belongs to.

**accountId** `string` *required*

Account the card is linked to.

**last4** `string`

Last four digits of the card number. May be absent. The full card number is never returned.

**nickname** `string` *required*

Display nickname of the card.

**type** `string` *required*

Card form factor. Values: `physical`, `virtual`.

**category** `string` *required*

Card category. Values: `debit`, `credit`.

**status** `string` *required*

Card status. Values: `pending`, `active`, `inactive`, `terminated`, `locked`, `unlockInProgress`. Terminated cards are listed like any other.

**cardholderName** `string` *required*

Name of the cardholder.

**expMonth** `integer` *required*

Expiration month (1-12).

**expYear** `integer` *required*

Expiration year.

**spendingLimits** `object` *required*

Spending limits as [Money](https://mcp.docs.relayfi.com/concepts/results.md#money) objects. Individual values may be `null` when no limit is set.

**SpendingLimits**

**dailyPurchase** `Money | null`

Daily purchase limit.

**dailyAtmWithdrawal** `Money | null`

Daily ATM withdrawal limit.

**monthlyPurchase** `Money | null`

Monthly purchase limit.

**createdAt** `string` *required*

Timestamp when the card was created, 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": 6,
  "method": "tools/call",
  "params": {
    "name": "list_cards",
    "arguments": {
      "intent": "User asked which cards are active and what their spending limits are.",
      "organizationId": "org_1",
      "pageSize": 10
    }
  }
}
```

```json Response theme={null}
{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "structuredContent": {
      "data": [
        {
          "object": "card",
          "id": "card_1",
          "organizationId": "org_1",
          "accountId": "acc_1",
          "last4": "4242",
          "nickname": "Marketing card",
          "type": "virtual",
          "category": "debit",
          "status": "active",
          "cardholderName": "Jane Doe",
          "expMonth": 11,
          "expYear": 2028,
          "spendingLimits": {
            "dailyPurchase": { "cents": 500000, "display": "5,000.00", "currency": "USD" },
            "dailyAtmWithdrawal": { "cents": 100000, "display": "1,000.00", "currency": "USD" },
            "monthlyPurchase": { "cents": 5000000, "display": "50,000.00", "currency": "USD" }
          },
          "createdAt": "2026-01-04T00:00:00.000Z"
        }
      ],
      "pagination": {
        "hasNextPage": false,
        "pageSize": 10
      }
    }
  }
}
```

## Notes

* The `last4` field may be absent. The full card number is never returned.
* Terminated cards are listed like any other. Filter by `status` in your agent logic if you need to exclude them.
* `spendingLimits` values are Money objects and may be `null`.
* Follow `nextCursor` until `hasNextPage` is `false`. Keep the same `pageSize` on every page.
* 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\_card](https://mcp.docs.relayfi.com/tools/get-card.md)
>
> Fetch a single card 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.