# Pinterest API guide



## Start with Pinterest



Discover public pins, inspect an individual pin and use boards to retain collection context. A pin URL, its image URL and its outbound destination are different references.



These requests use your API key and can spend credits. Check the current price on the endpoint page; each new page is a separate request. Later examples use illustrative identifiers: replace them with values from your earlier response.



### 1. Discover pins



Keep the query while following the returned cursor. Save pin URLs rather than using image URLs as pin identifiers. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/pinterest/search)



**pinterest/search**

```
curl "https://www.monocrawl.com/v1/pinterest/search?query=small%20garden%20design" \
  -H "x-api-key: mn_your_key_here"
```



### 2. Inspect a selected pin



Replace the example URL with a pin returned by search. Preserve the outbound source URL separately from the Pinterest citation. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/pinterest/pin)



**pinterest/pin**

```
curl "https://www.monocrawl.com/v1/pinterest/pin?url=https%3A%2F%2Fwww.pinterest.com%2Fpin%2F1126955506790868948" \
  -H "x-api-key: mn_your_key_here"
```



### 3. Read a known board



Supply a public board URL. Board collection is a separate read; follow only its returned continuation. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/pinterest/board)



**pinterest/board**

```
curl "https://www.monocrawl.com/v1/pinterest/board?url=https%3A%2F%2Fwww.pinterest.com%2Flizmrodgers%2Fmoms-night%2F" \
  -H "x-api-key: mn_your_key_here"
```



## Choose filters with the source behavior in mind



| Control | Behavior and limits |
| --- | --- |
| Continuation | Search and board reads have their own cursor; never move a token between them. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/pinterest/search) |
| References | Preserve the public pin URL, image URL and outbound source separately. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/pinterest/pin) |



Source availability, ordering and field coverage can change. Inspect warnings and partial-result metadata alongside the rows. See [runnable workflows](https://www.monocrawl.com/docs/workflows), [metric semantics](https://www.monocrawl.com/docs/metric-semantics), [computed fields](https://www.monocrawl.com/docs/computed-fields) and the [pagination matrix](https://www.monocrawl.com/docs/pagination).



## Match the operation to your task



| Your task | Endpoint | When to use it |
| --- | --- | --- |
| Boards owned by a known account | [`boards`](https://www.monocrawl.com/docs/endpoints/pinterest/boards) | Use a handle; this is a board directory, not a merged feed of every pin. |
| One pin and its source link | [`pin`](https://www.monocrawl.com/docs/endpoints/pinterest/pin) | Keep image, pin and external destination URLs in separate fields. |
| Keyword discovery | [`search`](https://www.monocrawl.com/docs/endpoints/pinterest/search) | Use a bounded collection budget; search ranking does not establish full coverage. |



Explore all documented operations by purpose below. Each endpoint reference contains its accepted parameters and current price.



### Other operations



- [`board`](https://www.monocrawl.com/docs/endpoints/pinterest/board)

- [`boards`](https://www.monocrawl.com/docs/endpoints/pinterest/boards)

- [`pin`](https://www.monocrawl.com/docs/endpoints/pinterest/pin)



### Search and discovery



- [`search`](https://www.monocrawl.com/docs/endpoints/pinterest/search)



## Endpoint reference

## pinterest/board

`GET /v1/pinterest/board`

The pins on a board, one page at a time, in the same pin shape as the search route.

*Pinterest board pins*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Board URL — e.g. `https://www.pinterest.com/lizmrodgers/moms-night/` |
| `cursor` | no | Opaque cursor from the previous page |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/pinterest/board?url=https%3A%2F%2Fwww.pinterest.com%2Flizmrodgers%2Fmoms-night%2F" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "cursor": null,
  "dropped": 0,
  "items": [
    {
      "author": {
        "handle": "example",
        "id": "example",
        "name": "example"
      },
      "board": "example",
      "description": "example",
      "domain": "example",
      "id": "example",
      "platform": "example",
      "title": "example",
      "url": "https://example.com/example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/pinterest/board#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/pinterest/board.json)


## pinterest/boards

`GET /v1/pinterest/boards`

A user's boards: name, URL, description, follower and pin counts, cover and created time.

*Pinterest boards*

| Parameter | Required | Description |
| --- | --- | --- |
| `handle` | yes | Pinterest username — e.g. `nasa` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/pinterest/boards?handle=nasa" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "cursor": null,
  "items": [
    {
      "cover_url": "https://example.com/example",
      "created_at": "2026-09-01T12:00:00Z",
      "description": "example",
      "followers": 0,
      "id": "example",
      "name": "example",
      "pin_count": 0,
      "platform": "example",
      "url": "https://example.com/example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/pinterest/boards#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/pinterest/boards.json)


## pinterest/pin

`GET /v1/pinterest/pin`

One pin: description, alt text, image, created time, save, share and reaction counts, pinner and original pinner.

*Pinterest pin*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Pin URL — e.g. `https://www.pinterest.com/pin/1126955506790868948` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/pinterest/pin?url=https%3A%2F%2Fwww.pinterest.com%2Fpin%2F1126955506790868948" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "author": {
    "followers": 0,
    "handle": "example",
    "id": "example",
    "name": "example",
    "verified_merchant": false
  },
  "created_at": "2026-09-01T12:00:00Z",
  "description": "example",
  "id": "example",
  "platform": "example",
  "stats": {
    "reactions": 0,
    "saves": 0,
    "shares": 0
  },
  "url": "https://example.com/example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/pinterest/pin#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/pinterest/pin.json)


## pinterest/search

`GET /v1/pinterest/search`

Search Pinterest pins by keyword: title, description, image and author. Paged by cursor.

*Pin search*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search term. — e.g. `living room decor` |
| `cursor` | no | Opaque cursor from the previous page. |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/pinterest/search?query=living%20room%20decor" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "cursor": null,
  "dropped": 0,
  "items": [
    {
      "alt_text": "example",
      "author": {
        "followers": 0,
        "handle": "example",
        "id": "example",
        "name": "example"
      },
      "board": "example",
      "created_at": "2026-09-01T12:00:00Z",
      "description": "example",
      "domain": "example",
      "id": "example",
      "image": "https://example.com/example",
      "is_promoted": false,
      "platform": "example",
      "title": "example",
      "url": "https://example.com/example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/pinterest/search#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/pinterest/search.json)