Pinterest board pins API
Pass a public Pinterest board URL and page its pins — compact metadata, images, and engagement — in the shared Social Fetch JSON envelope.
GET /v1/pinterest/boards/pins1 credit per successful request.
About this endpoint
Mood boards, competitor catalogs, and product inspiration feeds are usually organized as Pinterest boards, not as a bag of pin ids. Once you have a public board link (from a profile boards list, a shared URL, or a watchlist), the next job is to pull the pins on that board into structured rows: titles, images, outbound product links, who pinned each item, and save counts. Scraping infinite-scroll board HTML for every collection is brittle and duplicates work you already do for other social surfaces through Social Fetch.
`GET /v1/pinterest/boards/pins` takes a required board `url` query param. On a completed lookup, branch on `data.lookupStatus` (`found` or `not_found`), then read `data.pins` and `data.page`. Each pin is a compact row: id, url, title, description, outbound `link` and `domain`, dominantColor, createdAt, primary `image`, `pinner`, board summary, and metrics (saves, repins). Pass `cursor` when `data.page.hasMore` is true. Optional `trim=true` shrinks the payload.
This route pages pins for one board by URL. A profile's board catalog is `GET /v1/pinterest/profiles/{handle}/boards`. One pin by pin URL is `GET /v1/pinterest/pins`. Keyword discovery is `GET /v1/pinterest/search`. Pricing is 1 credit per successful completed request; confirm with `meta.creditsCharged` on every response.
Pinterest board pins API FAQ
How do I list pins on a Pinterest board via API?
Call `GET /v1/pinterest/boards/pins` with your Social Fetch API key (`x-api-key`) and a public board `url` query param. Read `data.lookupStatus`, then `data.pins` and `data.page`. Full parameters and examples are in the API docs.
How much does the Pinterest board pins endpoint cost?
Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth. Each paginated page is a separate billed request.
What board URL formats does this endpoint accept?
Public Pinterest board links, typically `https://www.pinterest.com/{username}/{board-slug}/`. Secret boards, private boards, and deleted collections resolve as `not_found`. Pass the link as the `url` query param.
How does pagination work on board pins?
Each response includes `data.page.nextCursor` and `data.page.hasMore`. When `hasMore` is true, pass `nextCursor` as the `cursor` query param on the next request. Keep the same board `url` across pages. The cursor is opaque — do not invent or parse it.
What fields are in each board pin row?
When `lookupStatus` is `found`, items in `data.pins` can include id, url, title, description, outbound link and domain, dominantColor, createdAt, primary image, pinner snapshot, board summary, and metrics (saves, repins). Fields may be null when Pinterest does not expose them. This is the compact pin shape, not the full single-pin payload from `GET /v1/pinterest/pins`.
Board pins vs profile boards vs pin by URL?
Use this route when you already have a board URL and need its pins. Use `GET /v1/pinterest/profiles/{handle}/boards` to list boards for a username. Use `GET /v1/pinterest/pins` for one pin by pin URL. They are separate paths on the Pinterest hub.
What does not_found mean for board pins?
`lookupStatus` of `not_found` means the board did not resolve to a public pin list. `data.pins` is empty. HTTP 200 still means the request finished; keep `meta.requestId` if you need support on that row.
Does this include secret or private boards?
No. Only publicly visible boards and pins. Secret boards and authenticated board management stay with Pinterest's official products.