---
title: "Retrieve cards"
---
After creating a card, you can use the [Get card](/api-reference/cards/get-v1-cards-card-id) endpoint to retrieve a single card's details. To retrieve all cards, use the [Get cards](/api-reference/cards/get-v1-cards) endpoint.

## Retrieve a single card

Use the [Get card](/api-reference/cards/get-v1-cards-card-id) endpoint to retrieve details of a specific card. Include your API key and the card id in the request:

```bash title="retrieve a single card request"
curl --request GET \
     --url https://api.gravv.xyz/v1/cards/<card id> \
     --header 'Api-Key: <API_KEY>'
     --header 'accept: application/json'
```

You will receive a response with the complete card details:

```json title="retrieve a single card response"
{
  "data": {
    "id": "dce0192a-9b3d-440b-9500-33dc9ac8dc20",
    "date_created": "2025-10-10T13:04:36.544962+01:00",
    "date_updated": "2025-10-13T17:57:26.56108+01:00",
    "spending_controls": {
      "activated": true,
      "daily_transaction_limit": 50,
      "type": "virtual"
    },
    "blockchain_network": "ethereum",
    "name_on_card": "Test User Name",
    "masked_pan": "9351",
    "expiry": "7/2029",
    "status": "active",
    "address": {
      "street": "Palo Alto",
      "city": "Palo Alto",
      "state": "California",
      "postal_code": "01023",
      "country_iso_code": "US"
    },
    "customer_id": "9e3cccad-e9ae-47a0-81ee-063af0159310",
    "currency": "USD",
    "network": "visa"
  },
  "error": null
}
```

## Retrieve all cards

Use the [Get cards](/api-reference/cards/get-v1-cards) endpoint to retrieve all cards with pagination support. Include your API key in the request:

```bash title="retrieve all cards request"
curl --request GET \
     --url https://api.gravv.xyz/v1/cards \
     --header 'Api-Key: <API_KEY>' \
     --header 'accept: application/json'
```

You will get a response similar to this:

```json title="retrieve all cards response"
{
  "data": {
    "items": [
      {
        "account_id": "9b40be8d-9d74-4d2a-8897-dea3ef80ad23",
        "address": {
          "city": "New York",
          "country_iso_code": "US",
          "postal_code": "10002",
          "state": "New York",
          "street": "201 Allen St"
        },
        "asset": "USDC",
        "blockchain_network": "polygon",
        "currency": "USD",
        "customer_id": "1805c3be-abca-4698-9cbd-789fc1d619eb",
        "date_created": "2025-12-05T10:48:18.170061Z",
        "date_updated": "2025-12-06T15:31:40.273281Z",
        "expiry": "8/2029",
        "id": "ac21ddfc-f6ba-432c-abb3-c5e2243e8ef7",
        "masked_pan": "9032",
        "name_on_card": "Jane Doe",
        "network": "visa",
        "proxy_address": "0x68603Ce66b3FEdC7834E697C19bb405c582B9278",
        "status": "active",
        "wallet_address": "0xa10a5f695dfe578a13b2d618a8ea8679d8d2036d"
      }
    ],
    "items_per_page": 1,
    "page": 1,
    "total_items": 1,
    "total_pages": 1
  },
  "error": null
}
```

### Get paginated results

You can set the number of results and navigate through pages using pagination parameters. The `page` parameter specifies which page to retrieve, and `items_per_page` specifies how many cards appear on each page:

```bash title="get paginated results request"
curl --request GET \
     --url 'https://api.gravv.xyz/v1/cards?page=2&items_per_page=20' \
     --header 'Api-Key: <API_KEY>'
     --header 'accept: application/json'
```

### Response fields

The response contains the following fields:

| Field                                      | Description                                                    |
| :----------------------------------------- | :------------------------------------------------------------- |
| id                                         | Unique identifier for the card                                 |
| date_created                               | Timestamp when the card was created                            |
| date_updated                               | Timestamp when the card was last updated                       |
| spending_controls                          | Object containing spending limit settings for the card         |
| spending_controls.activated                | Shows whether spending controls are active                     |
| spending_controls.single_transaction_limit | Maximum amount allowed per transaction in USD                  |
| spending_controls.daily_transaction_limit  | Maximum total spending allowed per day in USD                  |
| spending_controls.type                     | Card type, either virtual or physical                          |
| blockchain_network                         | Blockchain network backing the card                            |
| name_on_card                               | Name printed on the card                                       |
| masked_pan                                 | Last 4 digits of the card number                               |
| expiry                                     | Card expiration date in MM/YYYY format                         |
| status                                     | Current card status: active, freeze, or blocked                |
| address                                    | Object containing the billing address associated with the card |
| address.street                             | Street address                                                 |
| address.city                               | City name                                                      |
| address.state                              | State or region                                                |
| address.postal_code                        | Postal or ZIP code                                             |
| address.country_iso_code                   | Two-letter country code                                        |
| customer_id                                | ID of the customer who owns the card                           |
| currency                                   | Currency of the card                                           |
| network                                    | Payment network, either Visa or Mastercard                     |