Competing pins, average saves, related keywords and volume history — over HTTPS, in JSON. 15 lookups a month free, for as long as you have an account. No card, and no trial clock.
Every request carries your key in an Authorization header. Create one in the API tab of your dashboard — it is shown once.
Authorization: Bearer pp_live_YOUR_KEY_HERE
Base URL: https://api.pinpinterest.com/api/v1
Calling from a server, a Cloudflare Worker, or a ChatGPT / Claude connector? Use this base — it answers your code directly. The old base, https://pinpinterest.com/api/v1, keeps working, but it sits behind our bot protection, which can refuse requests from cloud hosts with an HTML 403.
What a call costs
Endpoints are either reads or lookups. Reads — /me, /check, /niches — are unlimited and never counted. Lookups come out of a monthly allowance that resets on the 1st.
A lookup that finds nothing is free. If we have no data for a keyword you get tracked: false, a list of near matches, and no charge.
…and on a paid plan it starts the crawl. That answer carries a crawl block: we queue the keyword, tell you when to ask again (retry_after_minutes) and e-mail you once it is in. Queueing costs no lookup.
Errors are free. A 4xx or 5xx never spends anything.
Batch charges per keyword resolved, not per request.
Read X-Quota-Remaining on any response to see where you stand without spending a call.
Plans
Plan
Lookups / month
Per minute
Endpoints
Free
15
10
5 of 12
Starter
5,000
60
9 of 12
Pro
50,000
120
12 of 12
Studio
200,000
240
12 of 12
Trial
300 for the trial
30
9 of 12
The Free plan is not a trial. It stays at 15 lookups a month for as long as you have an account, whether or not you ever subscribe.
While your free trial runs, your key works like Starter: the same endpoints and fields, with 300 lookups for the whole trial. When the trial ends it keeps the Free plan’s 15 a month.
demand is the word the app shows (high, medium or low; null under 5 pins), from the average saves of the pins that rank for the term. google_monthly_searches is Google's average monthly searches in the US over the last 12 months (Google Ads data, the figure Google Keyword Planner shows), read at google_searches_at; null until read, or when Google has no figure. It counts Google searches, not Pinterest searches: Pinterest does not publish monthly search counts. pinterest_search_count is Pinterest's own search count for the exact phrase, read from Pinterest's public interest page for it at pinterest_search_count_at, with that interest's pinterest_followers. Pinterest does not say what period the count covers, so compare phrases with it rather than reading it as searches per month. null when Pinterest has no interest for the exact phrase, or it has not been read yet; never 0.
…and when we have nothing for the term
{
"term": "quantum knitting for cats",
"tracked": false,
"message": "We have no data for this keyword yet. This lookup was not counted against your quota.",
"suggestions": [
{ "term": "knitting for beginners", "pins_analysed": 84 }
],
"crawl": {
"request_id": 137,
"status": "queued",
"retry_after_minutes": 10,
"queue_ahead": 0,
"message": "We are crawling Pinterest for this keyword now. Ask again in about 10 minutes — it costs nothing — or wait for the e-mail when it is in."
}
}
POST/v1/keywords/batch
Up to 50 keywords in one call. uses a lookupstarter+
Parameter
Type
Default
Notes
termsrequiredbody
string[]
—
Up to 50 keywords. Each one that returns data spends one lookup; misses are free.
demand is the word the app shows (high, medium or low; null under 5 pins), from the average saves of the pins that rank for the term. google_monthly_searches is Google's average monthly searches in the US over the last 12 months (Google Ads data, the figure Google Keyword Planner shows), read at google_searches_at; null until read, or when Google has no figure. It counts Google searches, not Pinterest searches: Pinterest does not publish monthly search counts. pinterest_search_count is Pinterest's own search count for the exact phrase, read from Pinterest's public interest page for it at pinterest_search_count_at, with that interest's pinterest_followers. Pinterest does not say what period the count covers, so compare phrases with it rather than reading it as searches per month. null when Pinterest has no interest for the exact phrase, or it has not been read yet; never 0.
POST/v1/keywords/request
Ask us to crawl keywords we do not have yet. We e-mail you once when they are in. free to callstarter+
Parameter
Type
Default
Notes
termsrequiredbody
string[]
—
Up to 25 keywords to crawl. Ones we already hold come back ready; each new one spends one of the 25 a day your account may start. Uses no lookup.
Which picture to draw: thumb_url (236 px wide) in a grid or a list, image_736_url (736 px wide) in a large view. Both are always a .jpg every browser shows, and null when a pin's picture is not on Pinterest's image host. image_url is the original as Pinterest keeps it and is unchanged: it can be several MB, or a HEIC photo that Chrome, Firefox and Android cannot draw. thumb_url and image_736_url were added on 24 Oct 2026.
GET/v1/keywords/trend
Daily demand history — the saves on the pins ranking for a term, day by day. uses a lookuppro+
The best-performing pins in a niche, sorted and paged. Off-topic subjects are filtered out. uses a lookuppro+
Parameter
Type
Default
Notes
nicherequired
slug
—
ONE slug from /v1/niches. Selecting a parent category includes every subniche beneath it.
sort
enum
saves
saves, clicks, engagement, velocity, reactions, recent. There is deliberately NO impressions option: Pinterest does not publish impressions for a pin you do not own, so we will not invent one. Each pin's `comments` field is always null: Pinterest does not publish a usable comment count, so we do not print one.
limit
int
24
How many pins per page, 1-50. Use `cursor` for the next page.
cursor
string
—
The next_cursor from the previous page. Paging is by POSITION, not page number, so a pin whose saves changed between two requests cannot repeat or vanish. Treat it as opaque.
min_saves
int
—
Only pins at or above this many saves.
video
0 | 1
—
1 for video pins only, 0 for images only. Omit for both.
max_age_days
int
—
Only pins Pinterest says were created within this many days. Pins with no known creation date are excluded when this is set.
{
"niche": "travel",
"niche_name": "Travel",
"sort": "saves",
"count": 24,
"pins": [
{
"pin_id": "1055599428648737000",
"title": "17 things to pack for a week in Lisbon",
"link": "https://example.com/lisbon-packing-list/",
"domain": "example.com",
"image_url": "https://i.pinimg.com/originals/ab/cd/ef/abcdef0123.jpg",
"thumb_url": "https://i.pinimg.com/236x/ab/cd/ef/abcdef0123.jpg",
"image_736_url": "https://i.pinimg.com/736x/ab/cd/ef/abcdef0123.jpg",
"saves": 48210,
"score": 91.4,
"is_video": false,
"reactions": 312,
"comments": null,
"est_clicks": 9640,
"velocity": 62.1,
"created_at_pin": "2026-04-02T00:00:00.000Z",
"account": { "username": "someblogger", "followers": 88400 },
"niche": { "slug": "travel", "name": "Travel" }
}
],
"filtered": { "removed": 9, "subjects": { "nails": 9 }, "note": "9 nail art & manicures pins filtered out of this niche." },
"next_cursor": "48210:1055599428648737000",
"has_more": true
}
Which picture to draw: thumb_url (236 px wide) in a grid or a list, image_736_url (736 px wide) in a large view. Both are always a .jpg every browser shows, and null when a pin's picture is not on Pinterest's image host. image_url is the original as Pinterest keeps it and is unchanged: it can be several MB, or a HEIC photo that Chrome, Firefox and Android cannot draw. thumb_url and image_736_url were added on 24 Oct 2026.
Keywords we do not have yet
Every keyword endpoint answers a term we have not crawled with tracked: false and a crawl block. On Starter, Pro and Studio (and a pass or Lifetime) the crawl has already been queued: status is queued or crawling, then ready — or failed, which means Pinterest has very little for that term, itself a finding. Ask again after retry_after_minutes; asking again is free and is the same request, never a second one. A crawl usually lands in 10–40 minutes, and we send one e-mail for a list that finishes within the hour, not one per keyword.
For a list, POST /v1/keywords/request takes up to 25 terms in one call, and GET /v1/keywords/request?id=… reports on them. An account may start 25 new crawls a day through the API. A free key’s miss says available_on_paid_plans and queues nothing.
Errors
Every error has the same shape, so you can switch on error.code:
The key is malformed, unknown, or has been revoked.
401
unauthorized
No key was sent. Use the Authorization header.
402
plan_required
Your plan does not include this endpoint. The body names the plan that does.
402
quota_exhausted
You have used this month’s lookups (or, on a trial key, the trial’s). The body carries the reset date, or the plan that lifts the cap. Retrying will not help until then.
403
forbidden
This key may not do that.
404
not_found
No such endpoint.
405
method_not_allowed
Wrong HTTP verb for this endpoint.
429
rate_limited
Too many requests this minute. Back off and retry — this did not use a lookup.
500
server_error
Our fault. Safe to retry.
503
not_configured
The service is temporarily unavailable.
Note that quota_exhausted is 402, not 429. Retrying does not help until the month turns over, so it is deliberately not a code that tells your client to back off and try again.
Get a key
Create an account, open the API tab, press Create key. The free allowance never expires.