# List board pins

Read up to 250 board pins per page, with a continuation cursor, explicit completeness and image or video evidence.

- Platform: [Pinterest](https://docs.upscrape.com/docs/platforms/pinterest)
- Capability ID: `pinterest.board-pins.list`
- Cost: 1 credit per request
- Maximum runtime: 45 seconds
- Execute endpoint: `POST https://data.upscrape.com/execute`

## Request

Use the exact public capability ID in the shared execute envelope.

```bash
curl --request POST \
  --url https://data.upscrape.com/execute \
  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Prefer: wait=30" \
  --data '{
  "input": {
    "limit": 25,
    "url": "https://www.pinterest.com/PinterestPredicts/gimme-gummy/"
  },
  "capability": "pinterest.board-pins.list"
}'
```

## Input


| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | `string` | No | Opaque continuation cursor returned by the previous page |
| `limit` | `integer` | No | Maximum pins returned in this page From 1 to 250. Default: `250`. |
| `url` | `string` | Yes | Full public Pinterest board URL |

### Example input

```json
{
  "limit": 25,
  "url": "https://www.pinterest.com/PinterestPredicts/gimme-gummy/"
}
```

## Response

Successful output is returned in `results[0].data`.

Raw platform output is intentionally open-ended and may evolve with the upstream source.

### Illustrative sample output

This example shows one response. Values and optional fields vary with the data available.

```json
{
  "board": {
    "id": "871517034080907898",
    "is_collaborative": false,
    "pin_count": 145,
    "privacy": "public",
    "section_count": 0,
    "url": "/pinterestpredicts/gimme-gummy/"
  },
  "items": [
    {
      "board": {
        "id": "871517034080907898",
        "is_collaborative": false,
        "pin_count": 0,
        "privacy": "public",
        "section_count": 0,
        "url": "/PinterestPredicts/gimme-gummy/"
      },
      "favorite_count": 0,
      "has_products": false,
      "id": "871516965411036700",
      "images": {
        "170x": {
          "height": 419,
          "url": "https://i.pinimg.com/236x/87/e0/76/87e076fc50c11492486f98cadfbd7ec0.jpg",
          "width": 236
        },
        "236x": {
          "height": 419,
          "url": "https://i.pinimg.com/236x/87/e0/76/87e076fc50c11492486f98cadfbd7ec0.jpg",
          "width": 236
        },
        "474x": {
          "height": 842,
          "url": "https://i.pinimg.com/474x/87/e0/76/87e076fc50c11492486f98cadfbd7ec0.jpg",
          "width": 474
        },
        "736x": {
          "height": 1280,
          "url": "https://i.pinimg.com/736x/87/e0/76/87e076fc50c11492486f98cadfbd7ec0.jpg",
          "width": 720
        },
        "orig": {
          "height": 1280,
          "url": "https://i.pinimg.com/originals/87/e0/76/87e076fc50c11492486f98cadfbd7ec0.jpg",
          "width": 720
        }
      },
      "is_native": false,
      "is_promoted": false,
      "is_repin": true,
      "is_story_pin": false,
      "is_video": false,
      "media_detection": "unverified",
      "media_type": "unknown",
      "repin_count": 28,
      "save_count": 140458
    },
    {
      "board": {
        "id": "871517034080907898",
        "is_collaborative": false,
        "pin_count": 0,
        "privacy": "public",
        "section_count": 0,
        "url": "/PinterestPredicts/gimme-gummy/"
      },
      "favorite_count": 0,
      "has_products": false,
      "id": "871516965411509619",
      "images": {
        "170x": {
          "height": 419,
          "url": "https://i.pinimg.com/236x/ef/83/b2/ef83b2788a7a9a873024d667458c7142.jpg",
          "width": 236
        },
        "236x": {
          "height": 419,
          "url": "https://i.pinimg.com/236x/ef/83/b2/ef83b2788a7a9a873024d667458c7142.jpg",
          "width": 236
        },
        "474x": {
          "height": 842,
          "url": "https://i.pinimg.com/474x/ef/83/b2/ef83b2788a7a9a873024d667458c7142.jpg",
          "width": 474
        },
        "736x": {
          "height": 1308,
          "url": "https://i.pinimg.com/736x/ef/83/b2/ef83b2788a7a9a873024d667458c7142.jpg",
          "width": 736
        },
        "orig": {
          "height": 2080,
          "url": "https://i.pinimg.com/originals/ef/83/b2/ef83b2788a7a9a873024d667458c7142.jpg",
          "width": 1170
        }
      },
      "is_native": false,
      "is_promoted": false,
      "is_repin": true,
      "is_story_pin": false,
      "is_video": true,
      "media_detection": "confirmed",
      "media_type": "video",
      "repin_count": 52,
      "save_count": 130036,
      "video_url": "https://v1.pinimg.com/videos/iht/av1Mp4-control-v2/0e/fb/1e/0efb1e25a593b9e9d30a95acc95c3c1e_720w.mp4"
    },
    {
      "board": {
        "id": "871517034080907898",
        "is_collaborative": false,
        "pin_count": 0,
        "privacy": "public",
        "section_count": 0,
        "url": "/PinterestPredicts/gimme-gummy/"
      },
      "favorite_count": 0,
      "has_products": false,
      "id": "871516965411802181",
      "images": {
        "170x": {
          "height": 229,
          "url": "https://i.pinimg.com/236x/97/ae/d2/97aed26a11b91385ad6a738d3ae734b4.jpg",
          "width": 236
        },
        "236x": {
          "height": 229,
          "url": "https://i.pinimg.com/236x/97/ae/d2/97aed26a11b91385ad6a738d3ae734b4.jpg",
          "width": 236
        },
        "474x": {
          "height": 460,
          "url": "https://i.pinimg.com/474x/97/ae/d2/97aed26a11b91385ad6a738d3ae734b4.jpg",
          "width": 474
        },
        "736x": {
          "height": 714,
          "url": "https://i.pinimg.com/736x/97/ae/d2/97aed26a11b91385ad6a738d3ae734b4.jpg",
          "width": 736
        },
        "orig": {
          "height": 954,
          "url": "https://i.pinimg.com/originals/97/ae/d2/97aed26a11b91385ad6a738d3ae734b4.jpg",
          "width": 983
        }
      },
      "is_native": false,
      "is_promoted": false,
      "is_repin": true,
      "is_story_pin": false,
      "is_video": false,
      "media_detection": "unverified",
      "media_type": "unknown",
      "repin_count": 351,
      "save_count": 11261
    }
  ],
  "outcome": {
    "reason": "upstream_pagination_ended_before_reported_count",
    "status": "incomplete"
  },
  "pagination": {
    "has_more": false,
    "retrieved_total": 102
  }
}
```
### Illustrative output fields

Derived from the sample above for orientation only. These fields are not a fixed response schema.

| Path | Observed type | Example |
| --- | --- | --- |
| `board` | `object` | 6 fields |
| `board.id` | `string` | 871517034080907898 |
| `board.is_collaborative` | `boolean` | false |
| `board.pin_count` | `integer` | 145 |
| `board.privacy` | `string` | public |
| `board.section_count` | `integer` | 0 |
| `board.url` | `string` | /pinterestpredicts/gimme-gummy/ |
| `items` | `array` | 3 items |
| `items` | `array` | 3 items |
| `outcome` | `object` | 2 fields |
| `outcome.reason` | `string` | upstream_pagination_ended_before_reported_count |
| `outcome.status` | `string` | incomplete |
| `pagination` | `object` | 2 fields |
| `pagination.has_more` | `boolean` | false |
| `pagination.retrieved_total` | `integer` | 102 |

## Execution behavior

A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job.

## Related documentation

- [Authentication](https://docs.upscrape.com/docs/api/authentication)
- [Jobs and results](https://docs.upscrape.com/docs/api/jobs)
- [Errors and retries](https://docs.upscrape.com/docs/api/errors)
- [Idempotency](https://docs.upscrape.com/docs/api/idempotency)