# Pinterest (/docs/pinterest)

Pinterest pins, boards, user boards, keyword search, and external-URL save counts through one unified API

Pinterest pins and their boards, a user's board list, keyword search across pins, and save counts for URLs that live outside Pinterest. Every endpoint is a `GET` and costs 1 credit.

Base URL: `/v1/pinterest/...`

  `url-stats` matches URLs **exactly**. `http://` and `https://`, and a trailing
  slash or not, count as different URLs and return different save counts. Pass
  the URL in the form people actually pin, usually the canonical one your site
  advertises, or you will read a real page as having zero saves.

## Quickstart

### 1. Find pins by keyword

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/pinterest/search?query=kitchen%20renovation" \
  -H "x-api-key: YOUR_API_KEY"
```

### 2. Fetch a board's pins

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/pinterest/board?url=https://www.pinterest.com/lizmrodgers/moms-night/" \
  -H "x-api-key: YOUR_API_KEY"
```

### 3. Read computed fields

When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include `engagement_rate`, `language`, `content_category`, and `estimated_reach`. See [Computed fields](/docs/computed-fields.md) for formulas, clamping rules, and null semantics.

## Discovery

| Endpoint                   | Credits | What it returns                                                          | Key parameters            |
| -------------------------- | ------- | ------------------------------------------------------------------------ | ------------------------- |
| `GET /v1/pinterest/search` | 1       | Pins matching a keyword: title, image URL, save count, author, and board | `query`, `cursor`, `trim` |
| `GET /v1/pinterest/pin`    | 1       | The fuller record: description, save and comment counts, author, board   | `url`, `trim`             |

Search rows are a summary. `pin` is the whole thing, so pull it only for the rows you actually care about.

## Boards

| Endpoint                        | Credits | What it returns                                                     | Key parameters          |
| ------------------------------- | ------- | ------------------------------------------------------------------- | ----------------------- |
| `GET /v1/pinterest/user/boards` | 1       | The boards a person has created, with title, pin count, cover image | `handle`, `trim`        |
| `GET /v1/pinterest/board`       | 1       | The pins inside one board, roughly 15 per page                      | `url`, `cursor`, `trim` |

That is the order: handle to boards, board URL to pins. Send `pagination.next_cursor` back as `cursor` to walk the rest of a board; `has_more` goes false on the last page. `user/boards` is a single fixed list with nothing to page.

List a person's boards, then pull the full record for any pin that stood out.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/pinterest/user/boards?handle=pinterest" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://www.socialcrawl.dev/v1/pinterest/pin?url=https://www.pinterest.com/pin/99360735500167749/" \
  -H "x-api-key: YOUR_API_KEY"
```

## Off-platform reach

| Endpoint                      | Credits | What it returns                                                           | Key parameters          |
| ----------------------------- | ------- | ------------------------------------------------------------------------- | ----------------------- |
| `GET /v1/pinterest/url-stats` | 1       | How many times each of up to 10 external URLs has been saved to Pinterest | `urls`, comma-separated |

This is the endpoint for measuring whether your own pages have any pull on Pinterest at all, and it works on URLs you do not control.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/pinterest/url-stats?urls=https://example.com/recipe,https://example.com/guide" \
  -H "x-api-key: YOUR_API_KEY"
```

## All endpoints

## Platform notes

**Save counts are keyed on the exact URL string.** Scheme, trailing slash, and query string each produce a different count, because URLs are passed through verbatim and never normalized.

**A count of 0 is ambiguous.** It means either "never pinned" or "page does not exist". Counts come from the Pinterest Save Button embed ecosystem, so pages outside it may undercount.

**`trim=true` costs the same.** It works on `search`, `pin`, `board`, and `user/boards`, and returns a lighter payload at the same price.

**Pinterest feeds other surfaces too.** It is one of the sources behind [`/v1/search/everywhere`](/docs/search/everywhere.md), so a cross-platform sweep picks it up without a separate call.

## Next steps

- [Pagination](/docs/pagination.md): Cursor and page walks, and what has_more actually means.
- [Credits](/docs/credits.md): What each tier costs and when a call is refunded.
- [API reference](/docs/api-reference.md): Every parameter and response field, endpoint by endpoint.
- [Instagram](/docs/instagram.md): The other visual-discovery surface, with hashtag and location feeds.
- [Universal search](/docs/search/everywhere.md): One keyword across Pinterest and every other source at once.