# Pinterest (/docs/pinterest)



Pinterest [#pinterest]

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/...`

Getting Started [#getting-started]

1\. Find pins by keyword [#1-find-pins-by-keyword]

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

2\. Fetch a board's pins [#2-fetch-a-boards-pins]

```bash
curl "https://www.socialcrawl.dev/v1/pinterest/board?url=https://www.pinterest.com/pinterest/official-pinterest-pins/" \
  -H "x-api-key: sc_your_api_key_here"
```

3\. Read computed fields [#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.

What you can get [#what-you-can-get]

**Discovery.** `GET /v1/pinterest/search` takes a `query` and returns matching pins with title, image URL, save count, author, and the board each belongs to. It is the only cursor-paginated endpoint here — pass `pagination.next_cursor` back as `cursor` to go deeper.

**One pin.** `GET /v1/pinterest/pin` takes the pin `url` and returns the fuller record: title, description, image URL, save count, comment count, author info, and board details. Search rows are a summary; this is the whole thing.

**Boards.** `GET /v1/pinterest/user/boards` takes a `handle` and lists the boards a person has created, each with title, description, pin count, and cover image. `GET /v1/pinterest/board` then takes a board `url` and returns a single page of the pins inside it. That is the order: handle to boards, board URL to pins.

**Off-platform reach.** `GET /v1/pinterest/url-stats` takes a `urls` parameter of up to 10 external URLs and reports how many times each has been saved to Pinterest through the Save Button. 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
# How much traction do these pages have on Pinterest?
curl "https://www.socialcrawl.dev/v1/pinterest/url-stats?urls=https://example.com/recipe,https://example.com/guide" \
  -H "x-api-key: sc_your_api_key_here"
```

<Callout type="warn">
  `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.
</Callout>

Typical flow [#typical-flow]

```bash
# 1. Whose boards?
curl "https://www.socialcrawl.dev/v1/pinterest/user/boards?handle=pinterest" \
  -H "x-api-key: sc_your_api_key_here"

# 2. What's on one of them?
curl "https://www.socialcrawl.dev/v1/pinterest/board?url=https://www.pinterest.com/pinterest/official-pinterest-pins/" \
  -H "x-api-key: sc_your_api_key_here"

# 3. Full detail on a pin that stood out
curl "https://www.socialcrawl.dev/v1/pinterest/pin?url=https://www.pinterest.com/pin/99360735500167749/" \
  -H "x-api-key: sc_your_api_key_here"
```

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

Pinterest is also a source behind [`/v1/search/everywhere`](/docs/search/everywhere.md), so a cross-platform sweep picks it up without a separate call.

Endpoints [#endpoints]

<PlatformEndpoints platform="pinterest" />

Notes [#notes]

* All endpoints use `GET` method with query parameters
* Authentication via `x-api-key` header
* Responses follow the unified SocialCrawl schema
* `search` takes `query`, `user/boards` takes a `handle`, `pin` and `board` take a `url`, and `url-stats` takes a comma-separated `urls` list of up to 10
* Only `search` paginates. `board` returns a single page of pins