Pinterest User Boards
A Pinterest board is a named collection of saved pins with a description, a cover image and a creation date, along with counts of its pins, followers, sections and collaborators and a flag showing whether other accounts may add to it. Read across a whole profile, those boards reveal which themes the account curates most heavily, which collections draw followers of their own, and where it opens the door to shared contributions.
Pinterest User Boards API Features
- Every board on a profileSend one or more Pinterest profile links in urls and the Pinterest User Boards API returns each board on those profiles as its own row, carrying the board's id and url.
- Size and audience of each boardmetrics.pins_count shows how much has been saved to a board and metrics.followers_count how many people follow it, which separates a busy archive from a collection with a real audience.
- Group boards and sectionsis_collaborative marks boards that other accounts can add pins to, metrics.collaborators_count says how many can, and metrics.sections_count shows how finely a board is subdivided.
- Name, description, cover and creation datename, text and cover_url say what a board is about at a glance, while published_at records when the board was created and so when that theme entered the account.
- Up to 500 boards per profileresults_limit is applied to each profile separately, defaults to 25 and accepts up to 500, so accounts that maintain hundreds of boards can be listed in full.
Pinterest User Boards API Parameters
| Parameters | Required | Description |
|---|---|---|
urls | Required | Pinterest profile links with a single username in the path, such as https://www.pinterest.com/marthastewart/; country domains like pinterest.co.uk or de.pinterest.com work too. |
results_limit | Optional | Maximum number of boards to return for each profile, an integer from 1 to 500. Defaults to 25. |
How to Use the Pinterest User Boards API
Submit profile links to the Pinterest User Boards API, wait for the task, then page through one row per board.
- Send the profile links and an optional results_limit to POST /v1/pinterest/user-boards and keep the task_id from the response.
- Call GET /v1/tasks/{task_id} every few seconds until status becomes succeeded.
- Read the boards from results.items; while has_more is true, request the next page with results.next_cursor.
curl -X POST "https://api.socq.ai/v1/pinterest/user-boards" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.pinterest.com/marthastewart/"],"results_limit":25}'
# Each board returned costs 0.5 credits.Pinterest User Boards API Use Cases
- Auditing a competitor's Pinterest themes: Line up board name and text against pins_count to see which subjects a brand keeps saving into, and against followers_count to see which of those collections people follow.
- Shortlisting creators by niche: Collect the boards of candidate creators with the Pinterest User Boards API and match board names and descriptions to your topic, keeping the accounts that curate it across several boards.
- Finding group boards worth joining: Keep the rows where is_collaborative is true and weigh collaborators_count against followers_count to pick shared boards with a following.
- Tracking which collections grow: Re-collect the same profiles on a schedule and compare pins_count and followers_count per board id to see which boards are gaining pins or followers.
Pinterest User Boards API Pro Tips
- Trim board and pin links back to the profile root before submitting, since urls takes https://www.pinterest.com/{username}/; board links belong in Pinterest Board Pins API.
- Raise results_limit above the default 25 when a profile keeps more boards than that; the limit counts per profile and only boards actually returned are charged.
- Group rows by author.username when one Pinterest User Boards API task covers several profiles, because every board carries the details of the account that owns it.
- Pass each board's url to Pinterest Board Pins API to pull its pins, using metrics.pins_count to decide how high to set that endpoint's results_limit.
Related APIs
Beyond the Pinterest User Boards 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 Board Pins API — Collect the pins on a Pinterest board from its board URL in board order, with pin text, the saving account, full-size images and pin links.
- Pinterest Topic API — Read Pinterest idea page URLs for each topic's monthly search count, refresh time and the narrower topics suggested under it.