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

Example curl

# 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

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.

{
  "count": 2,
  "updates": [
    {
      "card_desc": "James Wood 2022 Bowman Chrome Prospects Sapphire Baseball",
      "card_id": "1669693578344x525012276222885900",
      "card_number": "BCP-108",
      "card_set": "2022 Bowman Chrome Prospects Sapphire Baseball",
      "grade": "PSA 9",
      "player": "James Wood",
      "price": "53.88",
      "sale_date": "2023-07-15",
      "update_timestamp": "2023-07-16T01:29:01.227Z",
      "variant": "Base"
    },
    {
      "card_desc": "James Wood 2022 Bowman Chrome Prospects Sapphire Baseball",
      "card_id": "1669693578344x525012276222885900",
      "card_number": "BCP-108",
      "card_set": "2022 Bowman Chrome Prospects Sapphire Baseball",
      "grade": "PSA 10",
      "player": "James Wood",
      "price": "116.5",
      "sale_date": "2023-07-15",
      "update_timestamp": "2023-07-16T01:29:02.774Z",
      "variant": "Base"
    }
  ]
}