---
title: "Get Price Updates (Delta Poll)"
method: POST
path: "/v1/cards/price-updates"
tags: ["Market Data"]
---

# Get Price Updates (Delta Poll)

`POST /v1/cards/price-updates`

## Request

- Base URL: `https://api.cardhedger.com`
- URL: `https://api.cardhedger.com/v1/cards/price-updates`
- Auth: API key in header `X-API-Key`

Get price updates since a specified timestamp (delta polling).

> **New integrations: use the watchlist feed instead.** This endpoint
> returns the *global* tracked set — every subscribed card across all
> clients — which you must filter client-side. `POST
> /v1/cards/watchlist-updates` delivers only *your* watched cards'
> changes, with cursors that never expire and no `client_id` setup.

This endpoint enables efficient **delta polling** - clients only request data that has
changed since their last request, rather than fetching the entire dataset each time.

To add cards to the tracked set, see `subscribe-price-updates`.

## How Delta Polling Works

1. **Initial Request**: Make your first request with a timestamp from when you want to start tracking
2. **Store the Latest Timestamp**: Save the `update_timestamp` from the most recent item in the response
3. **Subsequent Requests**: Use that saved timestamp as the `since` parameter for your next request
4. **Repeat**: Continue polling at your desired interval (e.g., every 5 seconds)

## Polling Flow Example

```
Poll 1: since="2024-01-01T00:00:00.000Z"
Response: 50 updates, latest: "2024-01-01T01:30:00.000Z"
→ Save timestamp
                ↓ (wait 5 sec)
Poll 2: since="2024-01-01T01:30:00.000Z"
Response: 3 updates, latest: "2024-01-01T01:30:05.000Z"
→ Save timestamp
                ↓ (wait 5 sec)
Poll 3: since="2024-01-01T01:30:05.000Z"
Response: 0 updates (no new data)
→ Keep existing timestamp
```

## Parameters
- `since`: ISO 8601 timestamp to fetch updates after (e.g., '2023-07-16T01:28:57.000Z')
- `ignore_grades`: Optional list of grades to exclude (e.g., ['Raw'] to exclude ungraded cards)

## Best Practices

| Practice | Recommendation |
|----------|----------------|
| Poll Interval | 5-10 seconds for real-time updates |
| Checkpoint Storage | Persist `last_timestamp` to disk/database to resume after restarts |
| Empty Responses | Normal - means no new updates; keep your existing timestamp |
| Error Handling | On failure, retry with the same timestamp (don't advance it) |
| Grade Filtering | Use `ignore_grades` to reduce payload if you don't need all grades |

## Example curl

```bash
# Get all updates since timestamp
curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{"since": "2023-07-16T01:28:57.000Z"}' \
     "https://api.cardhedger.com/v1/cards/price-updates"

# Exclude Raw grades
curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{"since": "2023-07-16T01:28:57.000Z", "ignore_grades": ["Raw"]}' \
     "https://api.cardhedger.com/v1/cards/price-updates"
```

## Python Example

```python
import requests
import time
from datetime import datetime, timezone

API_KEY = "your-api-key"
BASE_URL = "https://api.cardhedger.com/v1/cards/price-updates"

# Start from current time
last_timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.000Z")

while True:
    response = requests.post(
        BASE_URL,
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={"since": last_timestamp, "ignore_grades": ["Raw"]}
    )
    data = response.json()

    if data["count"] > 0:
        for update in data["updates"]:
            print(f"{update['card_desc']} - {update['grade']}: ${update['price']}")
        # Update checkpoint to latest timestamp
        last_timestamp = data["updates"][-1]["update_timestamp"]

    time.sleep(5)  # Poll every 5 seconds
```

Returns list of price updates with card details and timestamps.

## Request body

- PriceUpdatesRequest: Request parameters for price updates endpoint.
  - `since` string, required: ISO timestamp to fetch updates since (e.g., '2023-07-16T01:28:57.000Z')
  - `ignore_grades` string[], nullable: List of grades to exclude from results (e.g., ['Raw'])

## Response `200`

Successful Response

- PriceUpdatesResponse: Response model for price updates endpoint.
  - `updates` PriceUpdate[], required: List of price updates since the specified timestamp
    - `price` string, required: Sale price
    - `sale_date` string, required: Date of the sale (YYYY-MM-DD)
    - `grade` string, required: Card grade (e.g., 'PSA 9', 'PSA 10', 'Raw')
    - `card_desc` string, required: Full card description
    - `card_set` string, required: Card set name
    - `card_number` string, required: Card number in set
    - `player` string, required: Player or character name
    - `variant` string, required: Card variant
    - `card_id` string, required: Unique card identifier
    - `update_timestamp` string, required: Timestamp when the price was updated (ISO format)
  - `count` integer, required: Number of updates returned

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/cardhedger/apis/card-hedge-api.md) - [All operations](https://skmtc.dev/cardhedger/apis/card-hedge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardhedger/apis/card-hedge-api/revisions/6de42f192a4d?raw)