Pinterest Board Pins
The pins on a Pinterest board are the images someone has gathered around one idea, each with a short title or description, the account that saved it and the original picture in its full width and height. Taken together in the order the board presents them, they form a ready-made visual reference set for mood boards, design research, image datasets and keeping an eye on how a curated collection changes.
Pinterest Board Pins API Features
- Pins kept in board orderRows from the Pinterest Board Pins API follow the sequence the board itself shows, so the collection reads the way its curator arranged it.
- Original image plus thumbnailmedia.url points to the full-size image and media.thumbnail_url to a small preview, with width and height in pixels for every file.
- Who saved it and what it saysauthor names the account that saved each pin, with its username, display name, profile link and avatar, and text carries the pin's title or description.
- A link back to every pinurl is the pin's own page, built from its id, so any image in the set can be traced to where it lives on Pinterest.
- Up to 1,000 pins from each boardresults_limit counts per board, defaults to 50 and accepts up to 1,000, and several boards can be sent together in urls.
Pinterest Board Pins API Parameters
| Parameters | Required | Description |
|---|---|---|
urls | Required | Pinterest board links in the /{username}/{board}/ form, such as https://www.pinterest.com/lizmrodgers/moms-night/. |
results_limit | Optional | Maximum number of pins to return for each board, an integer from 1 to 1000. Defaults to 50. |
How to Use the Pinterest Board Pins API
Send board links to the Pinterest Board Pins API, wait for the task, then read the pins page by page.
- POST the board links in urls, plus results_limit if you need more than 50 pins per board, to /v1/pinterest/board.
- Poll GET /v1/tasks/{task_id} with the task_id you received until the task has succeeded.
- Take the pins from results.items, and keep fetching with results.next_cursor for as long as has_more is true.
curl -X POST "https://api.socq.ai/v1/pinterest/board" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.pinterest.com/lizmrodgers/moms-night/"],"results_limit":50}'
# 0.5 credits per pin; boards that do not exist return no pins.Pinterest Board Pins API Use Cases
- Downloading a board's images: Save every media.url from a board to build a local reference library of the original files, using width and height to sort portrait and landscape shots.
- Building a captioned image dataset: Pair each image with the pin's text and the board it came from to assemble labelled examples for design research or model training.
- Watching a competitor's seasonal board: Collect the same board every week with the Pinterest Board Pins API and compare pin ids with the last run to see exactly what was added.
- Crediting sources in a mood board: Keep author.username and the pin url next to each image so every picture in a presentation can be credited and reopened.
Pinterest Board Pins API Pro Tips
- Give the Pinterest Board Pins API the board's own two-part link; profile tabs such as /{username}/_saved/ or /{username}/pins/, deeper section paths and pin.it short links are rejected, so open the board and copy its address.
- Check the board's metrics.pins_count with Pinterest User Boards API first, then set results_limit to match, so a large board is not cut off at the default 50.
- Load thumbnail_url for grids and previews and fetch media.url only for the images you keep, which saves bandwidth on boards with hundreds of pins.
Related APIs
Beyond the Pinterest Board Pins API, use these APIs when you need a different type of public Pinterest data.
- Pinterest Pins API — Resolve public Pin URLs into normalized content, creator, media, taxonomy, timestamps, and visible metrics.
- Pinterest User Pins API — Discover public Pins from profile URLs with a per-profile limit, normalized content, creator, media, timestamps, and visible metrics.
- Pinterest Profiles API — Collect public profile identity, bio, image, website, visible account counts, and collection context from profile URLs.
- Pinterest Search API — Search public Pins by text query with a result limit, returning normalized content, creator, media, taxonomy, timestamps, and visible metrics.
- Pinterest User Boards API — List the boards on Pinterest profiles from profile URLs, with names, descriptions, covers, creation dates and pin, follower, section and collaborator counts.
- Pinterest Topic API — Read Pinterest idea page URLs for each topic's monthly search count, refresh time and the narrower topics suggested under it.