---
updatedAt: 2026-09-01T22:39:58.000Z
agentTools:
  projectIndex: https://docs.mercury.com/llms.txt
---

# List cards

Retrieve a paginated list of cards.

**Retrieve cards.** List cards across your organization with filters by account, cardholder, status, type, and kind — or fetch a specific card by ID.

**Note:&#x20;**&#x4C;ist cards does not return sensitive card information such as PAN and CVC. These can be returned using the <Anchor target="_blank" href="https://docs.mercury.com/update/reference/vault">Vault API</Anchor>'s <Anchor target="_blank" href="https://docs.mercury.com/update/reference/revealcardpan">/revealcardpan endpoint</Anchor> for Agent cards only.

# OpenAPI definition

```json
{
  "components": {
    "schemas": {
      "Card": {
        "properties": {
          "accountId": {
            "description": " The Mercury account this card is associated with.",
            "type": "string"
          },
          "budgets": {
            "description": " One entry per active budget linked to this card and cardholder.\n Empty under cardLimit, or when this response has no active budget for the cardholder.",
            "items": {
              "$ref": "#/components/schemas/CardBudget"
            },
            "type": "array"
          },
          "categoryLocks": {
            "description": " Mercury spend-category locks applied to this card, in no particular order. Empty when the card has no category restrictions.",
            "items": {
              "$ref": "#/components/schemas/MercuryCategory"
            },
            "type": "array"
          },
          "createdAt": {
            "allOf": [
              {
                "$ref": "#/components/schemas/UTCTime"
              },
              {
                "description": " Timestamp when the card was issued."
              }
            ]
          },
          "expiration": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CardExpiration"
              },
              {
                "description": " Month and year the card expires."
              }
            ]
          },
          "id": {
            "description": " Unique identifier for the card.",
            "format": "uuid",
            "type": "string"
          },
          "isAgentCard": {
            "description": " Whether the card is managed by the agentic spend-management agent. Only agent\n cards can have their full details revealed.",
            "type": "boolean"
          },
          "isSingleUse": {
            "description": " Whether the card closes automatically after its first approved purchase. A used\n single-use card reports a @singleUseConsumed@ status.",
            "type": "boolean"
          },
          "kind": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CardKind"
              },
              {
                "description": " Whether the card is a debit or credit card."
              }
            ]
          },
          "lastFour": {
            "description": " Last four digits of the card's primary account number (PAN).",
            "type": "string"
          },
          "merchantLock": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MerchantInfo"
              },
              {
                "description": " Merchant lock applied to this card. Present only when the card is locked to a single merchant; otherwise omitted."
              }
            ],
            "nullable": true
          },
          "nameOnCard": {
            "description": " Cardholder name printed on the card.",
            "type": "string"
          },
          "nickname": {
            "description": " Optional user-assigned label for the card.",
            "nullable": true,
            "type": "string"
          },
          "physicalCardStatus": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PhysicalCardStatus"
              },
              {
                "description": " Activation state of a physical card. Null for virtual cards."
              }
            ],
            "nullable": true
          },
          "spendLimit": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SpendLimit"
              },
              {
                "description": " Card-level spending controls. This is null when card-level limits are\n unavailable, including for credit cards governed by budgets. For debit\n cards, this includes the underlying card limits even when budgets govern\n purchase spending. In budget mode, the transaction limit does not gate\n purchases, but the ATM or cash limit can still apply to cash withdrawals."
              }
            ],
            "nullable": true
          },
          "spendLimitType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SpendLimitType"
              },
              {
                "description": " Whether card-level limits or budgets govern purchase spending."
              }
            ]
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CardStatus"
              },
              {
                "description": " Current lifecycle state of the card."
              }
            ]
          },
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CardType"
              },
              {
                "description": " Whether the card is virtual (digital-only) or physical (printed, supports ATM)."
              }
            ]
          },
          "updatedAt": {
            "allOf": [
              {
                "$ref": "#/components/schemas/UTCTime"
              },
              {
                "description": " Timestamp of the last modification to the card or its settings."
              }
            ]
          },
          "userId": {
            "description": " Mercury User who owns the card.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "accountId",
          "createdAt",
          "updatedAt",
          "lastFour",
          "nameOnCard",
          "userId",
          "status",
          "type",
          "kind",
          "expiration",
          "spendLimitType",
          "budgets",
          "categoryLocks",
          "isAgentCard",
          "isSingleUse"
        ],
        "type": "object"
      },
      "CardBudget": {
        "description": " Current-cycle limits for one budget linked to this card and cardholder.",
        "properties": {
          "amountCents": {
            "description": " The cardholder's spend limit for the current budget cycle, in cents.",
            "minimum": 0,
            "type": "integer"
          },
          "id": {
            "description": "Unique identifier for a budget",
            "format": "uuid",
            "type": "string"
          },
          "name": {
            "description": " Display name of the budget.",
            "type": "string"
          },
          "remainingAmountCents": {
            "description": " Current-cycle limit minus recorded spend, clamped at zero, in cents.\n Authorization also uses cached allocations and in-flight holds, so its available amount may differ.",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "id",
          "name",
          "amountCents",
          "remainingAmountCents"
        ],
        "type": "object"
      },
      "CardExpiration": {
        "description": "Month and year the card expires.",
        "properties": {
          "month": {
            "description": "Calendar month.",
            "example": 8,
            "maximum": 12,
            "minimum": 1,
            "type": "integer"
          },
          "year": {
            "description": "Four-digit calendar year.",
            "example": 2026,
            "maximum": 2999,
            "minimum": 2000,
            "type": "integer"
          }
        },
        "required": [
          "month",
          "year"
        ],
        "type": "object"
      },
      "CardKind": {
        "enum": [
          "debit",
          "credit"
        ],
        "type": "string"
      },
      "CardListResponse": {
        "properties": {
          "cards": {
            "description": " List of cards in the current page.",
            "items": {
              "$ref": "#/components/schemas/Card"
            },
            "type": "array"
          },
          "page": {
            "description": " Pagination cursors for navigating to next/previous pages.",
            "properties": {
              "nextPage": {
                "description": "Unique identifier for a card",
                "format": "uuid",
                "type": "string"
              },
              "previousPage": {
                "description": "Unique identifier for a card",
                "format": "uuid",
                "type": "string"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "cards",
          "page"
        ],
        "type": "object"
      },
      "CardStatus": {
        "enum": [
          "active",
          "frozen",
          "cancelled",
          "inactive",
          "expired",
          "suspended",
          "singleUseConsumed"
        ],
        "type": "string"
      },
      "CardType": {
        "enum": [
          "virtual",
          "physical"
        ],
        "type": "string"
      },
      "MerchantId": {
        "format": "uuid",
        "type": "string"
      },
      "MerchantInfo": {
        "description": " Information about a merchant that can be used for spend controls like merchant locking.",
        "properties": {
          "id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MerchantId"
              }
            ]
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ],
        "type": "object"
      },
      "MercuryCategory": {
        "enum": [
          "Other",
          "Advertising",
          "Airlines",
          "AlcoholAndBars",
          "BooksAndNewspaper",
          "CarRental",
          "Charity",
          "Clothing",
          "Conferences",
          "Education",
          "Electronics",
          "Entertainment",
          "FacilitiesExpenses",
          "Fees",
          "FoodDelivery",
          "FuelAndGas",
          "Gambling",
          "GovernmentServices",
          "Grocery",
          "GroundTransportation",
          "Insurance",
          "InternetAndTelephone",
          "Legal",
          "Lodging",
          "Medical",
          "Memberships",
          "OfficeSupplies",
          "OtherTravel",
          "Parking",
          "Political",
          "ProfessionalServices",
          "Restaurants",
          "Retail",
          "RideshareAndTaxis",
          "Shipping",
          "Software",
          "Taxes",
          "Utilities",
          "VehicleExpenses"
        ],
        "type": "string"
      },
      "PhysicalCardStatus": {
        "enum": [
          "inactive",
          "active",
          "locked"
        ],
        "type": "string"
      },
      "SpendLimit": {
        "description": " Spending controls applied to a card",
        "properties": {
          "amountCents": {
            "description": " Maximum total spend allowed per interval, in cents.",
            "minimum": 0,
            "type": "integer"
          },
          "atmAmountCents": {
            "description": " Maximum ATM withdrawal allowed per interval, in cents. Null for virtual\n cards and credit cards.",
            "minimum": 0,
            "nullable": true,
            "type": "integer"
          },
          "interval": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SpendLimitInterval"
              },
              {
                "description": " Rolling window the limit applies to. Has no effect on single-use cards, which\n close after their first approved purchase."
              }
            ]
          }
        },
        "required": [
          "amountCents",
          "interval"
        ],
        "type": "object"
      },
      "SpendLimitInterval": {
        "enum": [
          "daily",
          "weekly",
          "monthly",
          "yearly"
        ],
        "type": "string"
      },
      "SpendLimitType": {
        "enum": [
          "cardLimit",
          "budgets"
        ],
        "type": "string"
      },
      "UTCTime": {
        "example": "2016-07-22T00:00:00Z",
        "format": "yyyy-mm-ddThh:MM:ssZ",
        "type": "string"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "description": "Bearer token authentication for Mercury API.\n\nUse your API token in the Authorization header:\n`Authorization: Bearer TOKEN`\n\nExample:\n`Authorization: Bearer secret-token:mercury_production_wma_24SCp4G81X3yHL4Wq8FgzuaP9ye3VKf2mgTDctXyRg5HY_yrucrem`\n\nYour Mercury API token should include the 'secret-token:' prefix.\nTokens can be generated from your Mercury dashboard settings.\n",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Streamline financial tasks with secure account management and transaction processing. Enables user registration, balance tracking, and payment handling.",
    "title": "Mercury API",
    "version": "1.0.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/cards": {
      "get": {
        "description": "Retrieve a paginated list of cards.",
        "operationId": "listCards",
        "parameters": [
          {
            "in": "query",
            "name": "accountId",
            "required": false,
            "schema": {
              "description": "Filter cards by one or more account IDs.",
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "description": "Filter cards by one or more statuses.",
              "items": {
                "enum": [
                  "active",
                  "frozen",
                  "cancelled",
                  "inactive",
                  "expired",
                  "suspended",
                  "singleUseConsumed"
                ],
                "type": "string"
              },
              "type": "array"
            }
          },
          {
            "in": "query",
            "name": "type",
            "required": false,
            "schema": {
              "description": "Filter cards by type (virtual or physical).",
              "items": {
                "enum": [
                  "virtual",
                  "physical"
                ],
                "type": "string"
              },
              "type": "array"
            }
          },
          {
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "description": "Filter cards by kind (debit or credit).",
              "items": {
                "enum": [
                  "debit",
                  "credit"
                ],
                "type": "string"
              },
              "type": "array"
            }
          },
          {
            "in": "query",
            "name": "userId",
            "required": false,
            "schema": {
              "description": "Filter cards by the cardholder's user ID.",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "isAgentCard",
            "required": false,
            "schema": {
              "description": "Filter cards by whether they are for Agent use.",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "isSingleUse",
            "required": false,
            "schema": {
              "description": "Filter cards by whether they are Single-use",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 500,
              "description": "Maximum number of results to return. Allowed range: 1 to 1000. Defaults to 500",
              "format": "int64",
              "maximum": 1000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "order",
            "required": false,
            "schema": {
              "default": "asc",
              "description": "Sort order. Can be 'asc' or 'desc'. Defaults to 'asc'",
              "enum": [
                "asc",
                "desc"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "start_after",
            "required": false,
            "schema": {
              "description": "The ID of the card to start the page after (exclusive). When provided, results will begin with the card immediately following this ID. Use this for standard forward pagination to get the next page of results. Cannot be combined with end_before.",
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "end_before",
            "required": false,
            "schema": {
              "description": "The ID of the card to end the page before (exclusive). When provided, results will end just before this ID and work backwards. Use this for reverse pagination or to retrieve previous pages. Cannot be combined with start_after.",
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardListResponse"
                }
              }
            },
            "description": ""
          },
          "400": {
            "description": "Invalid `end_before` or `start_after` or `order` or `limit` or `isSingleUse` or `isAgentCard` or `userId` or `kind` or `type` or `status` or `accountId`"
          }
        },
        "summary": "List cards",
        "tags": [
          "Cards"
        ]
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "servers": [
    {
      "description": "Mercury API URL",
      "url": "https://api.mercury.com/api/v1"
    }
  ],
  "tags": [
    {
      "description": "Manage cards",
      "name": "Cards"
    }
  ]
}
```