---
title: "List card sessions"
method: GET
path: "/card-sessions"
tags: ["Card Sessions"]
---

# List card sessions

`GET /card-sessions`

## Request

- Base URL: `https://api.natural.com`
- URL: `https://api.natural.com/card-sessions`
- Auth: HTTP bearer

List the card sessions you opened for the party you act for, newest first. It never includes card data.

## Query parameters

- `customerPartyId` string: Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf.
- `status` 'pending_approval' | 'approved' | 'declined' | 'claimed' | 'expired': Only sessions with this status.
- `reference` string: Only sessions created with this reference.
- `limit` integer: Maximum results per page.
- `cursor` string: Cursor from the previous page.

## Headers

- `X-Instance-ID` string, nullable

## Response `200`

Successful Response

- object
  - `data` object[], required
    - `sessionId` string, required
    - `cardId` string, required
    - `cardSource` 'natural_issued' | 'external', required: natural_issued: an agent card Natural issued to you. external: a card the user added on the dashboard.
    - `status` 'pending_approval' | 'approved' | 'declined' | 'claimed' | 'expired', required: pending_approval: waiting for the user; keep polling. approved: claim it now. declined: the user said no. claimed: already collected. expired: open a new session.
    - `allowedHosts` string[], required
    - `reference` string, nullable, required: The reference you created the session with. Null when you didn't set one.
    - `purchase` object, nullable, required: The purchase you created the session with, as the user saw it. Null for an agent card session opened without one.
      - `merchantName` string, required
      - `amount` integer, required: Minor units (cents) of `currency`. 0 means no purchase.
      - `currency` string, required
      - `description` string, nullable, required: The description you set. Null when you didn't.
    - `approvalExpiresAt` string, required: A pending session must be approved before this, 24 hours after creation. After it, an unapproved session is expired.
    - `claimExpiresAt` string, required: An approved session must be claimed before this: approval plus claimWindowSeconds. Until the user approves, it's the latest that could be: approvalExpiresAt plus claimWindowSeconds. After it, an unclaimed session is expired.
    - `claimedAt` string, nullable, required
    - `credentialExpiresAt` string, nullable, required: When the claimed proxy login stops working.
    - `createdAt` string, required
    - `agentToken` object, required: Agent token for this purchase, when you set requestAgentToken.
      - `requested` boolean, required: You set requestAgentToken when creating the session.
      - `mandateId` string, nullable, required: Once the session is approved: the mandate (amd_) to pay with. Create an agentic purchase with it (POST /agentic-payments/purchases) and claim that purchase's credential. Null when you didn't ask, while the session waits for approval, and when the card couldn't take agent payments, which is common: then claim this session and try the proxy.
    - `note` object, nullable, required: Cards the user added only, once the purchase is approved: a suggestion to pass on to the user. Null when there's nothing to suggest, and always null in list results: get the session for it.
      - `message` string, required: What to tell the user: what would let them skip the security code next time, such as verifying their identity or adding money to Natural.
      - `url` string, nullable, required: A page to send the user to for that step. Null when there's nothing to do yet.
  - `meta` object, required
    - `pagination` object, required
      - `hasMore` boolean, required: Whether more results are available.
      - `nextCursor` string, nullable, required: Cursor for the next page, or null when there are no more results.

## Other responses

- `400`: Validation Error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409`: Conflict
- `422`: Validation Error. The response contains one error object for each invalid request value.
- `428`: Precondition Required
- `429`: Too Many Requests
- `500`: Internal Server Error
- `501`: Not Implemented
- `502`: Bad Gateway
- `503`: Service Unavailable

## Changes

- **2026-10-26** `9327f52d75d3`: 1 info
  - added the required property `data/items/purchase` to the response with the `200` status
- **2026-10-22** `4fda009457be`: 1 info
  - added the required property `data/items/approvalExpiresAt` to the response with the `200` status
- **2026-10-15** `95af42ae53c7`: 1 info
  - added the required property `data/items/agentToken` to the response with the `200` status
- **2026-10-13** `af91bb69dfcf`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/natural/apis/natural-api/changes/card-sessions/get.md)

---

[API](https://skmtc.dev/natural/apis/natural-api.md) - [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) - [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/59c1208fa5dc?raw)