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 "https://www.socialcrawl.dev/v1/pinterest/search?query=kitchen%20renovation" \
-H "x-api-key: sc_your_key_here"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));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 "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 want | Call |
|---|---|
| Pins about a keyword | GET /v1/pinterest/search |
| One pin with its saves, reactions and comments | GET /v1/pinterest/pin |
| The pins on a board | GET /v1/pinterest/board |
| The boards a person has made | GET /v1/pinterest/user/boards |
| An account's followers, pin count and join date | GET /v1/pinterest/profile |
| How often a web page was saved to Pinterest | GET /v1/pinterest/url-stats |
| What people in a country are searching for | GET /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=engagementto fill them. - Pins with an encrypted
e1_id, whichpincannot read andinclude=engagementcannot 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
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/pinterest/search | 1 to 26 | Pins matching a keyword: title (or description), image URL, author, date; counts only with include=engagement | query, cursor, include, limit, trim |
GET /v1/pinterest/pin | 1 | The fuller record: text, save, reaction, comment and share counts, author, date | url, 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:
{
"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_urlsis 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.urlreads/pin/e1_...andpost.idis the base64 ofPin:e1_.... The same pin kept the same id across repeated calls, so it works for de-duplication, but Pinterest does not open ane1_link for a signed-out reader, andpincannot read it (404, 0 credits). For the same reasoninclude=engagementcannot fill these rows today: they stay null, cost nothing extra, and_warningscarriesengagement_unavailable(orengagement_partialwhen some rows were filled). - Page with
pagination.next_cursor. Send it back ascursor.data.next_cursorholds the same position in Pinterest's own form and is kept for integrations that already read it;pagination.next_cursoris the one to use.
Accounts
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/pinterest/profile | 1 | One account: name, bio, followers, following, pin and board counts, website, picture and the join date | handle 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 "https://www.socialcrawl.dev/v1/pinterest/profile?handle=pinterest" \
-H "x-api-key: YOUR_API_KEY"Boards
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/pinterest/user/boards | 1 | The boards a person has created, with title, pin count, cover image | handle, trim |
GET /v1/pinterest/board | 1 to 16 | The pins inside one board, up to 15 per page; pin dates only with include=engagement | url, 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 "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
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/pinterest/url-stats | 1 | How many times each of up to 10 external URLs has been saved to Pinterest | urls, 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 "https://www.socialcrawl.dev/v1/pinterest/url-stats?urls=https://example.com/recipe,https://example.com/guide" \
-H "x-api-key: YOUR_API_KEY"Trends
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 "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.
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.
| Endpoint | Path | Credit Tier |
|---|---|---|
| Get Pinterest board | /v1/pinterest/board | standard (1-16cr)metered |
| Get Pinterest pin details | /v1/pinterest/pin | standard (1cr) |
| Get a Pinterest profile | /v1/pinterest/profile | standard (1cr) |
| Search Pinterest pins | /v1/pinterest/search | standard (1-34cr)metered |
| Get Pinterest save counts for external URLs | /v1/pinterest/url-stats | standard (1cr) |
| List Pinterest user boards | /v1/pinterest/user/boards | standard (1cr) |
| Get Pinterest Trends for a country | /v1/pinterest/trends | premium (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
| Path | Rows per page | Date window | One call collects |
|---|---|---|---|
/v1/pinterest/board | varies | since and until, applied to each page fetched | up to 5,000 rows or 50 pages; limit up to 15 |
/v1/pinterest/search | varies | since and until, applied to each page fetched | up to 5,000 rows or 50 pages; limit up to 25 |
/v1/pinterest/user/boards | varies | since and until, applied to each page fetched | one 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
countryon/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.
| Path | Typical (median) | 95% finish within | Timeout to set |
|---|---|---|---|
/v1/pinterest/board | 5.2 s | 8.0 s | 16 s |
/v1/pinterest/pin | 3.8 s | 5.4 s | 12 s |
/v1/pinterest/search | 3.0 s | 6.9 s | 14 s |
/v1/pinterest/trends | 0.8 s | 1.5 s | 10 s |
/v1/pinterest/user/boards | 1.6 s | 2.4 s | 10 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
Pagination
Cursor and page walks, and what has_more actually means.
Credits
What each tier costs and when a call is refunded.
API reference
Every parameter and response field, endpoint by endpoint.
The other visual-discovery surface, with hashtag and location feeds.
Universal search
One keyword across Pinterest and every other source at once.
