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 the per-pin lookup can read 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.

Reading a search response

One row of GET /v1/pinterest/search?query=home%20decor%20ideas, captured on 19/10/2026 and trimmed to the post object:

{
  "post": {
    "id": "UGluOmUxX0FmcVBTaHhTckotZzdyRmtXVjY0NDA3SVNZZlItNnVWNVI4N1NrWG1SSkhab2h2a2JjX24=",
    "url": "https://www.pinterest.com/pin/e1_AfqPShxSrJ-g7rFkWV64407ISYfR-6uV5R87SkXmRJHZohvkbc_n",
    "content": {
      "text": "Hawthorne Vintage Wall Sconce | Traditional Brass Hallway Lighting",
      "media_urls": "https://i.pinimg.com/originals/51/16/90/511690c2692d705acee310f555cfc62f.jpg",
      "thumbnail_url": "https://i.pinimg.com/236x/51/16/90/511690c2692d705acee310f555cfc62f.jpg",
      "duration_seconds": null
    },
    "author": {
      "username": "HadleyJamesatHome",
      "display_name": "Hadley James at Home",
      "avatar_url": "https://i.pinimg.com/75x75_RS/78/17/d4/7817d41fa7183c02f9a164bc31994fd8.jpg",
      "verified": null
    },
    "engagement": { "views": null, "likes": null, "comments": null, "shares": null, "saves": null },
    "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false },
    "published_at": "2026-03-08T19:02:01.000Z",
    "ext": {
      "alt_text": "a wooden bench sitting under a large mirror next to a vase with flowers on it",
      "board_name": "Entryway Lighting & Design Ideas"
    }
  }
}

What to rely on:

• Rows are pins only. Pinterest's own module cards ("Explore featured boards", "Shop ...") are left out, so every row has an author, an image and a date.
• post.content.media_urls is one URL string on this endpoint, the original image. The unified schema allows a string or an array, so read it as either.
• Pin ids are encrypted. As of 19/10/2026 Pinterest returns search and board pins with an e1_ id: post.url reads /pin/e1_... and post.id is the base64 of Pin:e1_.... The same pin kept the same id across repeated calls, so it works for de-duplication, but Pinterest does not open an e1_ link for a signed-out reader, and pin cannot read it (404, 0 credits). For the same reason include=engagement cannot fill these rows today: they stay null, cost nothing extra, and _warnings carries engagement_unavailable (or engagement_partial when some rows were filled).
• Page with pagination.next_cursor. Send it back as cursor. data.next_cursor holds the same position in Pinterest's own form and is kept for integrations that already read it; pagination.next_cursor is the one to use.

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 the per-pin lookup can read 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 (including the encrypted e1_ pins described above) 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