SocialCrawl

Pinterest data API

Read pins, boards and search results from Pinterest with one key and one response shape.

Read Pinterest pins and their boards, a user's board list, keyword search across pins, Pinterest Trends for a country, and save counts for URLs that live outside Pinterest. Every endpoint is a GET. search and board with include=engagement add 1 credit for each row they fill.

url-stats matches URLs exactly. http:// and https://, and a trailing slash or not, count as different URLs and return different save counts. Pass the URL in the form people actually pin, usually the canonical one your site advertises, or you will read a real page as having zero saves.

Your first call

1. Find pins by keyword

cURL
curl "https://www.socialcrawl.dev/v1/pinterest/search?query=kitchen%20renovation" \
  -H "x-api-key: sc_your_key_here"
TypeScript
const url = new URL("https://www.socialcrawl.dev/v1/pinterest/search");
url.searchParams.set("query", "kitchen renovation");
const res = await fetch(url, {
  headers: { "x-api-key": process.env.SOCIALCRAWL_API_KEY! },
});
const { data } = await res.json();
console.log(data.items.map((row: { post: { url: string } }) => row.post.url));
Python
import os
import requests

res = requests.get(
    "https://www.socialcrawl.dev/v1/pinterest/search",
    headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]},
    params={"query": "kitchen renovation"},
)
for row in res.json()["data"]["items"]:
    print(row["post"]["url"])

Each row is one pin with its permalink, image, title, pinner and date. Measured on 22/11/2026: this call returned 16 pins for 1 credit and took about 5 seconds. The counts are null until you add include=engagement, and pagination.next_cursor walks to the next page.

2. Fetch a board's pins

cURL
curl "https://www.socialcrawl.dev/v1/pinterest/board?url=https://www.pinterest.com/lizmrodgers/moms-night/" \
  -H "x-api-key: sc_your_key_here"

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.

What it covers

What you wantCall
Pins about a keywordGET /v1/pinterest/search
One pin with its saves, reactions and commentsGET /v1/pinterest/pin
The pins on a boardGET /v1/pinterest/board
The boards a person has madeGET /v1/pinterest/user/boards
An account's followers, pin count and join dateGET /v1/pinterest/profile
How often a web page was saved to PinterestGET /v1/pinterest/url-stats
What people in a country are searching forGET /v1/pinterest/trends

What it does not cover

  • Private boards and anything behind a login.
  • Save counts on a search row. A plain search returns them null; add include=engagement to fill them.
  • Pins with an encrypted e1_ id, which pin cannot read and include=engagement cannot fill.
  • A page's save count when the page sits outside the Save Button ecosystem, which can undercount.
  • A date on a board pin without include=engagement.

Discovery

EndpointCreditsWhat it returnsKey parameters
GET /v1/pinterest/search1 to 26Pins matching a keyword: title (or description), image URL, author, date; counts only with include=engagementquery, cursor, include, limit, trim
GET /v1/pinterest/pin1The fuller record: text, save, reaction, comment and share counts, author, dateurl, trim

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:

Response
{
  "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.

Accounts

EndpointCreditsWhat it returnsKey parameters
GET /v1/pinterest/profile1One account: name, bio, followers, following, pin and board counts, website, picture and the join datehandle or url

Pins are author.posts_count, boards are author.ext.board_count and the date the account was created is author.joined_at. An unknown username answers 404 and is not charged.

cURL
curl "https://www.socialcrawl.dev/v1/pinterest/profile?handle=pinterest" \
  -H "x-api-key: YOUR_API_KEY"

Boards

EndpointCreditsWhat it returnsKey parameters
GET /v1/pinterest/user/boards1The boards a person has created, with title, pin count, cover imagehandle, trim
GET /v1/pinterest/board1 to 16The pins inside one board, up to 15 per page; pin dates only with include=engagementurl, cursor, include, limit, trim

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
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

EndpointCreditsWhat it returnsKey parameters
GET /v1/pinterest/url-stats1How many times each of up to 10 external URLs has been saved to Pinteresturls, comma-separated

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
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"

GET /v1/pinterest/trends takes a country and returns what people in that market search for, with no keyword needed. type picks the table: growing (the default), seasonal, top_monthly or top_yearly. Each item has a rank, the term, a search_index from 0 to 100 within the answer, and the weekly, monthly and yearly change. Narrow it with include and exclude, both comma-separated keywords. A filter that matches nothing returns 404 at no charge.

cURL
curl "https://www.socialcrawl.dev/v1/pinterest/trends?country=US&type=growing" \
  -H "x-api-key: sc_your_key_here"

Questions people ask

Why are saves null on Pinterest search results?

Pinterest's search results carry no counts, so on a plain GET /v1/pinterest/search call post.engagement.saves, likes, comments and shares are null on every row. Add include=engagement to join each row to its pin lookup, which fills them at 1 credit per row filled, up to 25 rows. Rows with an encrypted e1_ pin id cannot be looked up, stay null and are refunded, and _warnings says engagement_unavailable or engagement_partial.

How do I check how many times my pages were saved to Pinterest?

Send up to 10 URLs, comma-separated, to GET /v1/pinterest/url-stats?urls=. Counts are keyed on the exact URL string, so http and https, and a trailing slash or not, give different counts. Pass the canonical form people pin. A count of 0 means either never pinned or the page does not exist.

Python
import os
import requests

res = requests.get(
    "https://www.socialcrawl.dev/v1/pinterest/url-stats",
    headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]},
    params={"urls": "https://example.com/recipe,https://example.com/guide"},
)
print(res.json()["data"])

All endpoints

7 endpoints available.

EndpointPathCredit Tier
Get Pinterest board/v1/pinterest/boardstandard (1-16cr)metered
Get Pinterest pin details/v1/pinterest/pinstandard (1cr)
Get a Pinterest profile/v1/pinterest/profilestandard (1cr)
Search Pinterest pins/v1/pinterest/searchstandard (1-34cr)metered
Get Pinterest save counts for external URLs/v1/pinterest/url-statsstandard (1cr)
List Pinterest user boards/v1/pinterest/user/boardsstandard (1cr)
Get Pinterest Trends for a country/v1/pinterest/trendspremium (10cr)

How far back and how deep

Each list returns one page at a time. Send cursor for the next page, or max_items or max_pages to collect several pages in one call. A page size appears only where it has been verified. How paging works

PathRows per pageDate windowOne call collects
/v1/pinterest/boardvariessince and until, applied to each page fetchedup to 5,000 rows or 50 pages; limit up to 15
/v1/pinterest/searchvariessince and until, applied to each page fetchedup to 5,000 rows or 50 pages; limit up to 25
/v1/pinterest/user/boardsvariessince and until, applied to each page fetchedone page a call

Country and region

country and region do different jobs on different endpoints. Each line below says what the parameter does there. How they differ

  • country on /v1/pinterest/trends: ISO country code, in any case: AR, AU, BR, CA, CO, DE, EG, ES, FR, GB, ID, IE, IN, IT, KR, MX, MY, NZ, PH, SA, TH, TR, US. Pinterest publishes no list for other countries, and one of them is a free 400. IE reads Pinterest's GB+IE list and AU and NZ read AU+NZ; GB alone has its own list. Defaults to US.

How long a call takes

Measured on production calls that were not served from the cache, 14/10/2026 to 21/10/2026. A cached call answers faster. Set your client timeout to the value in Timeout to set, so a slow call is not cut off and sent again.

PathTypical (median)95% finish withinTimeout to set
/v1/pinterest/board5.2 s8.0 s16 s
/v1/pinterest/pin3.8 s5.4 s12 s
/v1/pinterest/search3.0 s6.9 s14 s
/v1/pinterest/trends0.8 s1.5 s10 s
/v1/pinterest/user/boards1.6 s2.4 s10 s

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