> ## Documentation Index
> Fetch the complete documentation index at: https://dev.phygitals.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List recent pulls

> Returns the most recent pulls across one or more packs, newest first.

Returns the most recent pulls across one or more packs, ordered newest first. Use this to drive a live "recent pulls" feed on a pack detail page or a pack-list dashboard.

## Query parameters

<ParamField query="claw_ids" type="string[]">
  Pack identifiers (each is the `id` returned by [`/api/v1/vm/available`](/api-reference/packs/list)). Repeat the parameter to filter by multiple packs:

  ```http theme={"dark"}
  GET /api/v1/vm/recent-pulls?claw_ids=BSG6Dy...&claw_ids=GFkLm...
  ```

  Omit to return recent pulls across **all** packs.
</ParamField>

<ParamField query="limit" default="20" type="integer">
  Maximum number of pulls to return. Clamped to the range `[1, 100]`; non-numeric values fall back to the default of `20`.
</ParamField>

## Example request

```http theme={"dark"}
GET /api/v1/vm/recent-pulls?claw_ids=BSG6DyEihFFtfvxtL9mKYsvTwiZXB1rq5gARMTJC2xAM&limit=10
X-API-Key: <your_api_key>
```

## Response

<ResponseExample>
  ```json 200 theme={"dark"}
  [
    {
      "id": "v1|110586049456|0",
      "claw_id": "BSG6DyEihFFtfvxtL9mKYsvTwiZXB1rq5gARMTJC2xAM",
      "claw_slug": "topps-chrome-2024",
      "value": 250.0,
      "buyback_price": 212.5,
      "created_at": "2026-04-30T17:42:11.123Z",
      "metadata": {
        "name": "2024 Topps Chrome Juan Soto RC Auto /25",
        "image": "https://cdn.phygitals.com/cards/soto-rc-auto.png",
        "back_image": "https://cdn.phygitals.com/cards/soto-rc-auto-back.png",
        "attributes": [
          { "trait_type": "Sport", "value": "Baseball" },
          { "trait_type": "Year", "value": "2024" }
        ]
      }
    },
    {
      "id": "v1|110586049457|0",
      "claw_id": "BSG6DyEihFFtfvxtL9mKYsvTwiZXB1rq5gARMTJC2xAM",
      "claw_slug": "topps-chrome-2024",
      "value": 82.5,
      "buyback_price": 70.13,
      "created_at": "2026-04-30T17:42:11.123Z",
      "metadata": {
        "name": "2024 Topps Chrome Common Card",
        "image": "https://cdn.phygitals.com/cards/common.png",
        "back_image": null,
        "attributes": []
      }
    }
  ]
  ```
</ResponseExample>

## Fields

<ResponseField name="id" type="string">
  Item identifier. Equal to `mint_address` for items already minted on-chain, otherwise the source listing id (e.g. eBay listing id).
</ResponseField>

<ResponseField name="claw_id" type="string">
  The pack the item was pulled from. Matches the `id` returned by [`/api/v1/vm/available`](/api-reference/packs/list) and the `claw_id` accepted by [`/api/v1/vm/buyback`](/api-reference/sellback).
</ResponseField>

<ResponseField name="claw_slug" type="string | null">
  URL-friendly slug of the pack. Same value as the `slug` returned by [`/api/v1/vm/available`](/api-reference/packs/list). `null` for packs without a slug configured.
</ResponseField>

<ResponseField name="value" type="number">
  Fair-market value of the pulled item in USD.

  For real production pulls this is the live FMV recorded on the source listing (eBay listing's `fmv` or the on-chain item's `altFmv`). For sandbox-only synthetic pulls this is approximated as `buyback_price / 0.85` because the sandbox does not store the original FMV.
</ResponseField>

<ResponseField name="buyback_price" type="number">
  Sellback price in USD: `value * pack.buyback_percent`. Use as the canonical "what we'd pay back" amount.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp the pull was recorded.
</ResponseField>

<ResponseField name="metadata" type="object">
  Standard NFT metadata for the pulled item.

  * `name` — Item name.
  * `image` — CDN URL for the item image.
  * `back_image` — CDN URL for the card back image, or `null` when not available.
  * `attributes` — Array of `{ trait_type, value }` entries.
</ResponseField>

## Errors

| Status | Body                                          | Meaning                                             |
| ------ | --------------------------------------------- | --------------------------------------------------- |
| `500`  | `{ "error": "An unexpected error occurred" }` | Internal error while building the recent-pull list. |

Unknown `claw_ids`, an empty result set, and unparseable `limit` values do **not** error: the response is `200 []` (or `200` with whatever subset of pulls match) and `limit` falls back to the default of `20`.