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, except search and board with include=engagement, which add 1 credit for each row they fill.

Base URL: /v1/pinterest/...

Quickstart

1. Find pins by keyword

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

2. Fetch a board's pins

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 for formulas, clamping rules, and null semantics. Where an endpoint supports them, list rows also carry judged labels (computed.labels, computed.relevance) by default at no extra credits; see Labels.

Discovery

Search rows carry no counts of their own. Add include=engagement and each row is filled with its save, reaction, comment and share counts at 1 extra credit per row filled, up to 25 rows; rows that cannot be filled are refunded, and limit caps how many rows are served and filled. Many pins have no title or description at all, so content.text can be null on a search row.

Boards

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.

Board pins carry their save, comment and share counts but not the date they were created, and the reaction count only when the pin has reactions. Add include=engagement and each pin is filled with its creation date and reaction count at 1 extra credit per row filled, up to 15 rows; counts the board already carried are kept, rows that cannot be filled are refunded, and limit caps how many rows are served and filled. It works on every page of the walk, with or without cursor.

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

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

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.

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

6 endpoints available.

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, so a cross-platform sweep picks it up without a separate call.

Next steps