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
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.
{
"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.
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.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
}
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. The body carries the reset date. 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.