FeaturesPricingAPIGuidesBlogAboutFAQContact
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

PlanLookups / monthPer minuteEndpoints
Free15104 of 8
Starter5,000606 of 8
Pro50,0001208 of 8
Studio200,0002408 of 8

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
}

POST/v1/keywords/batch

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

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/top-pins

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

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+

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

Errors

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

{ "error": { "code": "quota_exhausted", "message": "…" }, "docs": "…" }
StatusCodeMeaning
400bad_requestThe request could not be parsed.
400validation_failedA required parameter is missing or unusable.
401invalid_api_keyThe key is malformed, unknown, or has been revoked.
401unauthorizedNo key was sent. Use the Authorization header.
402plan_requiredYour plan does not include this endpoint. The body names the plan that does.
402quota_exhaustedYou have used this month’s lookups. The body carries the reset date. Retrying will not help until then.
403forbiddenThis key may not do that.
404not_foundNo such endpoint.
405method_not_allowedWrong HTTP verb for this endpoint.
429rate_limitedToo many requests this minute. Back off and retry — this did not use a lookup.
500server_errorOur fault. Safe to retry.
503not_configuredThe 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]