API — Pinterest keyword data

API

The Pinterest keyword API

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.

Authentication

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://pinpinterest.com/api/v1

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.
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 10
Starter	5,000	60	7 of 10
Pro	50,000	120	10 of 10
Studio	200,000	240	10 of 10

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.

Endpoints

GET`/v1/me`

Your plan, quota and reset date. free to call

curl "https://pinpinterest.com/api/v1/me" \
  -H "Authorization: Bearer pp_live_YOUR_KEY_HERE"

Example response

{
  "account": { "email": "[email protected]", "plan": "free", "plan_label": "Free" },
  "quota": {
    "limit": 15,
    "used": 3,
    "remaining": 12,
    "resets_at": "2026-09-01T00:00:00.000Z",
    "resets_label": "1 Sep",
    "note": "A lookup that finds no data does not count against this."
  },
  "rate_limit": { "per_minute": 10, "remaining": 10 },
  "fields": ["term","tracked","pinsAnalysed","pinCount","niche","competition","avgSaves","maxSaves","totalSaves","estClicks","opportunity"]
}

GET`/v1/check`

Verify a key works. Costs no quota. free to call

curl "https://pinpinterest.com/api/v1/check" \
  -H "Authorization: Bearer pp_live_YOUR_KEY_HERE"

Example response

{ "ok": true, "account": { "email": "[email protected]", "plan": "free", "plan_label": "Free" } }

GET`/v1/niches`

The niche taxonomy we classify keywords into. free to call

curl "https://pinpinterest.com/api/v1/niches" \
  -H "Authorization: Bearer pp_live_YOUR_KEY_HERE"

Example response

{
  "niches": [ { "slug": "food-drink", "name": "Food & Drink", "children": [ { "slug": "air-fryer", "name": "Air Fryer" } ] } ],
  "count": 1
}

GET`/v1/keywords/search`

Look up one keyword. The core call. uses a lookup

Parameter	Type	Default	Notes
`term`required	`string`	—	The keyword to look up. A term we do not hold answers tracked:false and costs no lookup.

curl "https://pinpinterest.com/api/v1/keywords/search?term=air+fryer+recipes" \
  -H "Authorization: Bearer pp_live_YOUR_KEY_HERE"

Example response

{
  "keyword": {
    "term": "air fryer recipes",
    "tracked": true,
    "pins_analysed": 213,
    "competition": "high",
    "avg_saves": 4821,
    "total_saves": 1026873,
    "est_clicks": 118440,
    "opportunity": 3390,
    "niche": { "name": "Food & Drink", "slug": "food-drink" }
  }
}

…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 }
  ]
}

POST`/v1/keywords/batch`

Up to 50 keywords in one call. uses a lookupstarter+

Parameter	Type	Default	Notes
`terms`requiredbody	`string[]`	—	Up to 50 keywords. Each one that returns data spends one lookup; misses are free.

curl -X POST "https://pinpinterest.com/api/v1/keywords/batch" \
  -H "Authorization: Bearer pp_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"terms":["air fryer recipes","meal prep"]}'

Example response

{
  "results": [
    { "term": "air fryer recipes", "tracked": true, "pins_analysed": 213, "avg_saves": 310 },
    { "term": "made up term", "tracked": false }
  ],
  "requested": 2,
  "found": 1,
  "charged": 1,
  "truncated": false
}

GET`/v1/keywords/related`

Keywords that co-occur with yours. uses a lookupstarter+

Parameter	Type	Default	Notes
`term`required	`string`	—	The keyword to find neighbours for.
`limit`	`int`	`20`	How many neighbours to return, 1-50.

curl "https://pinpinterest.com/api/v1/keywords/related?term=air+fryer+recipes" \
  -H "Authorization: Bearer pp_live_YOUR_KEY_HERE"

Example response

{
  "term": "air fryer recipes",
  "tracked": true,
  "sampled_pins": 400,
  "related": [
    { "term": "air fryer chicken", "shared_pins": 96, "overlap": 0.24, "pins_analysed": 118, "competition": "high" }
  ]
}

GET`/v1/keywords/top-pins`

The best-performing pins for a keyword. uses a lookuppro+

Parameter	Type	Default	Notes
`term`required	`string`	—	The keyword whose ranking pins you want.
`limit`	`int`	`10`	How many pins to return, 1-50, best first.

curl "https://pinpinterest.com/api/v1/keywords/top-pins?term=air+fryer+recipes" \
  -H "Authorization: Bearer pp_live_YOUR_KEY_HERE"

Example response

{
  "term": "air fryer recipes",
  "tracked": true,
  "pins": [
    {
      "pin_id": "1234567890",
      "title": "15 Easy Air Fryer Dinners",
      "domain": "example.com",
      "saves": 8400,
      "score": 412.5,
      "rank": 1
    }
  ]
}

GET`/v1/keywords/trend`

Daily demand history — the saves on the pins ranking for a term, day by day. uses a lookuppro+

Parameter	Type	Default	Notes
`term`required	`string`	—	The keyword to chart.
`days`	`int`	`90`	How far back to go.

curl "https://pinpinterest.com/api/v1/keywords/trend?term=air+fryer+recipes" \
  -H "Authorization: Bearer pp_live_YOUR_KEY_HERE"

Example response

{
  "term": "air fryer recipes",
  "tracked": true,
  "days": 90,
  "points": [ { "day": "2026-06-01", "volume": 88000 } ]
}

GET`/v1/trending`

Topics rising in a niche right now, from the pins people are publishing this month. uses a lookup

Parameter	Type	Default	Notes
`niche`required	`slug`	—	One to five comma-separated slugs from /v1/niches. `niches` also works.
`days`	`int`	`45`	The window the rising reading is measured over.
`limit`	`int`	`12`	How many topics to return.

curl "https://pinpinterest.com/api/v1/trending?niche=home-decor" \
  -H "Authorization: Bearer pp_live_YOUR_KEY_HERE"

Example response

{
  "niche": "home-decor",
  "niche_name": "Home Decor",
  "window_days": 45,
  "country": "US",
  "countries": ["US"],
  "fresh": true,
  "data_through": "2026-08-27",
  "data_age_days": 7,
  "stale_reason": null,
  "sample": {
    "recent": 4000,
    "baseline": 4000,
    "recent_from": "2026-08-15",
    "recent_to": "2026-08-27",
    "baseline_from": "2026-07-01",
    "baseline_to": "2026-07-05"
  },
  "message": "12 topics rising in Home Decor, from 4000 pins published through 2026-08-27.",
  "topics": [
    {
      "topic": "cozy living room",
      "pins": 91,
      "accounts": 90,
      "domains": 14,
      "baseline_pins": 22,
      "lift": 3.65,
      "score": 12.4,
      "examples": [
        { "title": "Cozy Living Room Ideas with Warm Neutral Decor", "saves": 412, "pin_id": "1234567890" }
      ]
    }
  ],
  "generic_terms": ["decor", "living room", "bedroom"]
}

GET`/v1/niches/top-pins`

The best-performing pins in a niche, sorted and paged. Off-topic subjects are filtered out. uses a lookuppro+

Parameter	Type	Default	Notes
`niche`required	`slug`	—	ONE slug from /v1/niches. Selecting a parent category includes every subniche beneath it.
`sort`	`enum`	`saves`	saves, clicks, engagement, velocity, reactions, comments, 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.
`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.

curl "https://pinpinterest.com/api/v1/niches/top-pins?niche=travel&sort=saves&limit=24" \
  -H "Authorization: Bearer pp_live_YOUR_KEY_HERE"

Example response

{
  "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": 44,
      "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
}

Errors

Every error has the same shape, so you can switch on error.code:

{ "error": { "code": "quota_exhausted", "message": "…" }, "docs": "…" }

Status	Code	Meaning
400	`bad_request`	The request could not be parsed.
400	`validation_failed`	A required parameter is missing or unusable.
401	`invalid_api_key`	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.

Every plan includes an API allowance — see what each one gets · Questions? Email [email protected]

The Pinterest keyword API

Authentication

What a call costs

Plans

Endpoints

GET/v1/me

GET/v1/check

GET/v1/niches

GET/v1/keywords/search

POST/v1/keywords/batch

GET/v1/keywords/related

GET/v1/keywords/top-pins

GET/v1/keywords/trend

GET/v1/trending

GET/v1/niches/top-pins

Errors

Get a key

GET`/v1/me`

GET`/v1/check`

GET`/v1/niches`

GET`/v1/keywords/search`

POST`/v1/keywords/batch`

GET`/v1/keywords/related`

GET`/v1/keywords/top-pins`

GET`/v1/keywords/trend`

GET`/v1/trending`

GET`/v1/niches/top-pins`