# Using the CardSight AI API - Collection Set Progress API

## Overview
Track progress toward completing card sets within a collection. Returns summary statistics across all sets plus detailed per-set progress including owned cards, missing card UUIDs, completion percentage, and estimated cost to complete.

## Endpoint Details
- **Method**: GET
- **URL**: `https://api.cardsight.ai/v1/collection/{collectionId}/set-progress`
- **Authentication**: API Key required (X-Api-Key header)

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| collectionId | UUID | Yes | - | Collection UUID (path parameter) |
| take | integer | No | 20 | Results per page (1-100) |
| skip | integer | No | 0 | Number of results to skip |
| sortBy | string | No | "completion" | Sort by: `completion`, `missing`, `cost`, `difficulty` |
| order | string | No | "desc" | Sort order: `asc` or `desc` |
| minCompletion | number | No | - | Filter sets with minimum completion percentage (0-100) |
| nearComplete | boolean | No | - | Filter for sets >80% complete |

## Using the CardSight AI SDK (Recommended)

### Node.js / TypeScript
```typescript
import { CardSightAI } from 'cardsightai'

const client = new CardSightAI({ apiKey: 'your-api-key' })

const response = await client.collections.setProgress('550e8400-e29b-41d4-a716-446655440000', {
  sortBy: 'completion',
  order: 'desc',
  take: 20
})

// Always check for errors
if (response.error) {
  console.error('Error:', response.error)
} else {
  const { summary, sets, total_count } = response.data

  // Summary statistics
  console.log(`Total sets: ${summary.totalSets}`)
  console.log(`Near complete (>80%): ${summary.nearCompleteSets}`)
  console.log(`Fully complete: ${summary.fullyCompleteSets}`)

  if (summary.totalEstimatedCost) {
    console.log(`Cost to complete all: $${summary.totalEstimatedCost}`)
  }

  // Per-set progress
  for (const set of sets) {
    console.log(`\n${set.setName} (${set.releaseName} ${set.releaseYear})`)
    console.log(`  Progress: ${set.ownedCards}/${set.totalCards} (${set.completionPercentage}%)`)

    if (set.estimatedCostToComplete) {
      console.log(`  Cost to complete: $${set.estimatedCostToComplete}`)
    }

    if (set.difficultyScore !== undefined) {
      console.log(`  Difficulty: ${set.difficultyScore}/100`)
    }

    // Missing cards (UUIDs) - only populated for sets >= 85% complete
    if (set.missingCards.length > 0 && set.missingCards.length <= 20) {
      console.log(`  Missing card IDs: ${set.missingCards.join(', ')}`)
    }
  }
}

// Filter to near-complete sets only
const nearComplete = await client.collections.setProgress('550e8400-e29b-41d4-a716-446655440000', {
  nearComplete: true,
  sortBy: 'missing',
  order: 'asc'
})
```

### Python
```python
from cardsightai import CardSightAI

client = CardSightAI(api_key='your-api-key')

response = client.collections.set_progress(
    '550e8400-e29b-41d4-a716-446655440000',
    sort_by='completion',
    order='desc'
)

# Summary
print(f"Total sets: {response.summary.total_sets}")
print(f"Near complete: {response.summary.near_complete_sets}")
print(f"Fully complete: {response.summary.fully_complete_sets}")

# Per-set progress
for set in response.sets:
    print(f"{set.set_name}: {set.owned_cards}/{set.total_cards} ({set.completion_percentage}%)")
```

## Direct API Call (cURL)
```bash
# Get all set progress sorted by completion
curl -X GET "https://api.cardsight.ai/v1/collection/550e8400-e29b-41d4-a716-446655440000/set-progress?sortBy=completion&order=desc" \
  -H "X-Api-Key: your-api-key"

# Filter to near-complete sets (>80%)
curl -X GET "https://api.cardsight.ai/v1/collection/550e8400-e29b-41d4-a716-446655440000/set-progress?nearComplete=true" \
  -H "X-Api-Key: your-api-key"

# Sort by cost to complete (cheapest first)
curl -X GET "https://api.cardsight.ai/v1/collection/550e8400-e29b-41d4-a716-446655440000/set-progress?sortBy=cost&order=asc" \
  -H "X-Api-Key: your-api-key"
```

## Example Response
```json
{
  "summary": {
    "totalSets": 12,
    "nearCompleteSets": 3,
    "fullyCompleteSets": 1,
    "totalEstimatedCost": "485.00"
  },
  "sets": [
    {
      "setId": "550e8400-e29b-41d4-a716-446655440001",
      "setName": "Base Set",
      "releaseName": "2023 Topps Chrome",
      "releaseYear": "2023",
      "totalCards": 220,
      "ownedCards": 215,
      "missingCards": [
        "550e8400-e29b-41d4-a716-446655440010",
        "550e8400-e29b-41d4-a716-446655440011",
        "550e8400-e29b-41d4-a716-446655440012",
        "550e8400-e29b-41d4-a716-446655440013",
        "550e8400-e29b-41d4-a716-446655440014"
      ],
      "completionPercentage": 97.7,
      "estimatedCostToComplete": "45.00",
      "difficultyScore": 25,
      "averageCardValue": "2.50"
    },
    {
      "setId": "550e8400-e29b-41d4-a716-446655440002",
      "setName": "Rookie Autographs",
      "releaseName": "2023 Topps Chrome",
      "releaseYear": "2023",
      "totalCards": 50,
      "ownedCards": 12,
      "missingCards": [],
      "completionPercentage": 24.0,
      "estimatedCostToComplete": "1250.00",
      "difficultyScore": 85,
      "averageCardValue": "45.00"
    }
  ],
  "total_count": 12,
  "skip": 0,
  "take": 20
}
```

## Response Fields

The response contains 3 required sections: `summary`, `sets`, and pagination fields.

### summary (required)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| totalSets | number | Yes | Total number of sets represented in collection |
| nearCompleteSets | number | Yes | Number of sets >80% complete |
| fullyCompleteSets | number | Yes | Number of fully complete sets (100%) |
| totalEstimatedCost | string | No | Total cost to complete all sets (USD) |

### sets (required) - Array of SetProgress

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| setId | UUID | Yes | Set identifier |
| setName | string | Yes | Name of the set |
| releaseName | string | Yes | Name of the release |
| releaseYear | string | Yes | Year of the release |
| totalCards | number | Yes | Total cards in set |
| ownedCards | number | Yes | Number of unique cards owned |
| missingCards | array | Yes | Array of missing card UUIDs (populated for sets ≥85% complete) |
| completionPercentage | number | Yes | Completion percentage (0-100) |
| estimatedCostToComplete | string | No | Estimated cost to acquire missing cards (USD) |
| difficultyScore | number | No | Difficulty score based on card availability (0-100) |
| averageCardValue | string | No | Average value per card in set (USD) |

### Pagination Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| total_count | number | Yes | Total number of sets matching filters |
| skip | number | Yes | Number of sets skipped |
| take | number | Yes | Number of sets returned |

## Related Endpoints

| Endpoint | Description |
|----------|-------------|
| `/v1/collection/{collectionId}/set-progress/{setId}` | Get progress for a specific set |
| `/v1/collection/{collectionId}/set-progress/{setId}/{parallelId}` | Track parallel completion within a set |

## Common Use Cases
- Track set completion progress across entire collection
- Identify sets that are close to completion
- Calculate cost to complete specific sets
- Focus buying decisions on near-complete or low-cost sets
- Generate want lists using missing card UUIDs
- Compare difficulty scores to find easier sets to complete

## Tips for AI Assistants
- **Note on IDs:** your `collectionId` (and other resources you create) are stable and yours to keep — saving cards to a collection or list is the recommended way to hold onto them for the long term. The catalog references inside a collection — the `setId` and the card UUIDs in `missingCards` — can be used to pull fresh details from the catalog. See the FAQ for how IDs should be used.
- The SDK returns `{ data, error }` - always check for errors first
- URL uses singular "collection": `/v1/collection/{collectionId}/set-progress`
- Response has a `summary` section with aggregate stats plus `sets` array with per-set details
- `missingCards` is an **array of UUIDs**, not a count - only populated for sets ≥85% complete
- For sets <85% complete, calculate missing count as `totalCards - ownedCards`
- Dollar values (`estimatedCostToComplete`, `averageCardValue`, `totalEstimatedCost`) are strings
- Use `sortBy=cost&order=asc` to find cheapest sets to complete
- Use `sortBy=difficulty&order=asc` to find easiest sets to complete
- Use `nearComplete=true` to focus on sets >80% done
- Only base cards are considered (parallels excluded from this endpoint)