Search Pinterest pins with 5-swatch hex palettes & shop-the-look domains

GET/v1/pins/search· Updated 2026-11-15

Searches real-time Pinterest pins by aesthetic or product keyword. Returns HD image URLs, exact pixel dimensions & aspect ratio (2:3, 3:4), extracted dominant hex color + 5-swatch palette, save velocity, creator metadata, and outbound e-commerce merchant domain. Cost: 2 Credits / pin returned (min 4 Credits; 0 Credits if empty).

Parameters

querystringrequired
Visual aesthetic, interior style, or product keyword (also accepts alias q or keyword).
limitinteger (1 to 50)
Maximum pins to return per page (1–50, default 20).
cursorstring
Opaque pagination bookmark cursor from data.next_cursor.
colorstring
Optional 6-digit hex color filter (e.g. #C9B096 or C9B096).

Example Request (cURL / Python / JavaScript)

curl "https://api.pindataapi.com/v1/pins/search?query=" \
  -H "x-api-key: pn_live_your_api_key"

import requests

res = requests.get(
    "https://api.pindataapi.com/v1/pins/search?query=",
    headers={"x-api-key": "pn_live_your_api_key"},
    timeout=30,
)
print(res.json())

const res = await fetch("https://api.pindataapi.com/v1/pins/search?query=", {
  headers: { "x-api-key": "pn_live_your_api_key" },
});
const data = await res.json();
console.log(data);

Live Response Preview

{
  "code": 0,
  "provider": "https://pindataapi.com",
  "status": "ok",
  "msg": "success",
  "data": {
    "query": "ceramic mug",
    "count": 2,
    "next_cursor": "Y2JVSG81V2sxcmNHRlpWM1J5VFVad1YxWllhRlJXTVVZMldWVlZOV0pIUlhsa00zQlhVbXhhVkZWWGMzaGphemxXVm14U1dGTkZTbEZXYlhSWFkyMVdWMVZzYkdwU2JIQlFWV3hvVTJWV1pISlhhM1JYVm10V05sVldVbE5XVlRGWFUyNUdZVlpXVlRGVmJGcEhWbFpPY2s5WGJGZGlSbXQ0Vm10amVHUXhWbkpPVmxwUFZtMW9WMVpyV21GVlJuQllUVlpPYW1KR1JqUldWM1JMWVRBeFdWRnNXbFpXYldnelYxWmtSMk50UmpaUmJHaFhUVEJLZUZkclVrSk5SMVpYVjJ4c2FGSlViSE5aYkZVd1pXeGFSVkZzVGxkTmEzQlhWRlpTWVdGRk1IbGhSVGxYWVRGd2FGcEZXbE5qTVhCSFdrZHNVMVpGVlhsV01uUnJUVVpTYzFOWWFGTlhSMUpXVm14a1UxSXhVbk5YYm1SWFZtdGFNRmxWWkVkVk1VbDNUVlJXVjFKc1duWlVhMXBTWlVaT2MxcEhSbE5TTWswMVdtdGFWMU5YU2paVmJYaFRWMGRvUmxkc1ZsZGhNV1J6VjFod2FGSkdjRmxaYTJSdVpXeHdWbFpVUms5aVJUVmFWMnRWTVZVeFNsWldhbFpYVWtWS1ZGVXlNVmRqYXpWWFZteFNWMUpZUWxCWGJHUTBWbXN4UjFSWWJHdFNNMUpYV1d0YVMxSldhM2RWYlRsV1VtdHNNMVpzYUhkV1YwWnlZMFZrVlZaRlducFViWGhIVjFad1JrOVdaRk5XTTFFd1ZtdGplR1F4V1hsU2JrNXBVMFZhVTFZd1pHOVZSbkJZWkVWMGFsSnNTbFpWTW5Rd1lWWktWV0pGYkZkU2VrWXpWa1JLUjJSR2JEWlJiR2hwVWpGS1NWZFdXbUZrTVdSSFUyNVNhVkp1UW05WldIQlhUVVpaZUZWcmRGWmlWbHA1VkZab1IxVnNXa2RYYlVaWFlXdEtNMWt3V210WFJURldaRWRzVTJKWWFGcFdiRnBUVkRGc1dGSnVTbWhOTWxKV1ZteGtVMWRHYkhOV1ZFWlBZa2hCTWxWdGN6RmhWMHAwWVVaR1YxWXphR2haVkVFMVVXeENWVTFVYUU1V1IwNDFWRlZTUW1Rd05YRmFNMnhPWld4V05WUnRjRTVOVlRsRVkwVm9WbFpZWkhoYWExSkdaV3N4V0ZWWVpGcFdSMUp2VjFod1NrNUZOVlZSVkVKYVZrWldORlJZY0dwbFZuQkZWMjB4VUZKR2NIRlVWbVJXWldzeFdGZFVTazlpVldzd1YxaHdXbVZzY0VWU1ZFcFFWa2Q0YjFSVlpFWk9WbkIwVTFob1QyRnRVbkpVVmxKQ1RrWnNjV0pIYkU5V1JrWTFWMnhTVDA5R1VuSldiR2h0VVZRd09XWkVSVE5OYWtGM1RVUlpORTFxVFRGTmFsbDZUbFJuY1ZJeFJrMUxibmhyV2xkS2FFMTZXVE5hVjAwd1dsUlNhazFYUlRKWmFtc3hUMFJTYkU1SFdUQmFWR2N4V2xkTk1VNHlWbXRQUkdzeVQxZFpNazVYUlhkWlZFRjZUWHBuZWsxVVpHdE9hbFpzV2tkT2FscFVUbTFaYlZKb1prVTFSbFl6ZHowPXxVSG80ZGxveWFESlVSelUxWlVkMFdWSlVNV1pOYWtKbVRGUkdPRTFVWTNsTlJFRjNUbXBuZVUxNlZYbE9hazB4VDBOd1NGVlZkM0ZtUjFFeFRrZFZNMWxYUlRGWmVsazBXV3BaTlU1RVRtMVpWRWt3VGxSQ2FscEVWWHBaYWtab1RtcFZkMDE2UVRWTk1razBUMGRaTUUxVWJHeE5hbFY0V2tSa2FWcHFRbXROUkdzMVdrUkJOVTlIVlRWTlIwbzRWR3RXV0daQlBUMD18Tm9uZXwxNzIwMDA2ODIzNTI2MzU4KkdRTCp8YmZkMjJiN2Y1Yzk1NmY3NGZhYjZjYzk1YzBmNWJhYjlkYzNiNmZlYzE0ZDgwYzk1YzI5YTNiODI2YmNjNjYxMXxORVd8",
    "dominant_palette_summary": [
      "#C9B096",
      "#D0CDC1",
      "#C5C4C4",
      "#B2B2B0"
    ],
    "pins": [
      {
        "pin_id": "e1_AfqPShwhDXqkIA5FsIxyvJT-zZSIZUd-KpOe2rI_meOHpzVVwnCd",
        "numeric_id": null,
        "title": "LEMON COFFEE MUG",
        "description": "Elevate your coffee or tea experience with the Casa Amarosa Lemon Coffee Mug. Made from high-quality stoneware, this mug is sleek and durableperfect for any modern home or office. The wide opening and ergonomic handle make it easy and comfortable to use. Material: Stoneware Size: 3.5 Inch x 3 Inch Capacity: 250 ml Color: Yellow Handmade by artisans. Perfect cup for coffee and tea.",
        "alt_text": "a blue and white coffee cup with an orange design on the inside, sitting on a table",
        "dominant_color": "#C9B096",
        "palette_hex": [
          "#C9B096",
          "#FFFFFF",
          "#EAEAEB",
          "#EAEAEC",
          "#3A7FC2"
        ],
        "image_url": "https://i.pinimg.com/originals/69/ba/88/69ba885b9ab40879c14b8979873039c1.jpg",
        "thumbnail_url": "https://i.pinimg.com/236x/69/ba/88/69ba885b9ab40879c14b8979873039c1.jpg",
        "width": 1080,
        "height": 1620,
        "aspect_ratio": "2:3",
        "saves_count": 1,
        "comments_count": 0,
        "reactions_count": 1,
        "is_shoppable": true,
        "price_value": null,
        "price_currency": null,
        "merchant_domain": "garmentory.com",
        "outbound_url": "https://garmentory.com/sale/casa-amarosa/drinkware-coffee-tea/2651956-casa-amarosa-lemon-coffee-mug",
        "pin_url": "https://www.pinterest.com/pin/e1_AfqPShwhDXqkIA5FsIxyvJT-zZSIZUd-KpOe2rI_meOHpzVVwnCd/",
        "creator": {
          "username": "preview_garmentory_com",
          "full_name": "Pinterest Preview Garmentory",
          "followers": 327,
          "verified_merchant": false,
          "avatar_url": "https://s.pinimg.com/images/user/default_140.png"
        },
        "board": {
          "board_id": "872783671476146896",
          "name": "Coffee & Tea Cups",
          "url": "https://www.pinterest.com/preview_garmentory_com/_products_coffee-tea-cups/",
          "pin_count": 2707
        },
        "created_at": "Wed, 01 Oct 2025 22:22:19 +0000",
        "search_query": "ceramic mug"
      },
      {
        "pin_id": "e1_AfqPShzMmtz4EFK2Zr9GN_fmBkt2Sqs9QZqNR-ydvNKMsuvZqqj7",
        "numeric_id": null,
        "title": "Whimsical Frog Mug, Handmade Ceramic Art Cup, Collectible Frog Sculpture, Funny Animal Coffee Mug, Unique Gift for Frog Lovers, Pottery Art - Etsy",
        "description": "Whimsical Ceramic Art Mug – Handmade Frog Cup – Collectible Pottery Sculpture – Funny Animal Coffee Mug - Etsy",
        "alt_text": "a ceramic mug with eyes and legs sitting next to coffee beans",
        "dominant_color": "#D0CDC1",
        "palette_hex": [
          "#D0CDC1",
          "#E5DFD3",
          "#F6F0E5",
          "#755E57",
          "#817C72"
        ],
        "image_url": "https://i.pinimg.com/originals/57/77/d6/5777d6b70b2c473b8c420eefef932d04.webp",
        "thumbnail_url": "https://i.pinimg.com/236x/57/77/d6/5777d6b70b2c473b8c420eefef932d04.jpg",
        "width": 1024,
        "height": 1536,
        "aspect_ratio": "2:3",
        "saves_count": 18,
        "comments_count": 0,
        "reactions_count": 18,
        "is_shoppable": true,
        "price_value": null,
        "price_currency": null,
        "merchant_domain": "etsy.com",
        "outbound_url": "https://www.etsy.com/listing/4313873589/whimsical-ceramic-art-mug-handmade-frog?ref=share_ios_native_control",
        "pin_url": "https://www.pinterest.com/pin/e1_AfqPShzMmtz4EFK2Zr9GN_fmBkt2Sqs9QZqNR-ydvNKMsuvZqqj7/",
        "creator": {
          "username": "cbsoules",
          "full_name": "Carol Soules",
          "followers": 174,
          "verified_merchant": false,
          "avatar_url": "https://i.pinimg.com/140x140_RS/3b/e3/69/3be3690ce7424bdcc04b4c104aa0dff5.jpg"
        },
        "board": {
          "board_id": "218213613134357670",
          "name": "Hand built pottery ideas",
          "url": "https://www.pinterest.com/cbsoules/hand-built-pottery-ideas/",
          "pin_count": 248
        },
        "created_at": "Fri, 06 Mar 2026 04:05:59 +0000",
        "search_query": "ceramic mug"
      }
    ]
  },
  "meta": {
    "request_id": "11d407c7-a85d-499e-b37a-5b8d34ff5841",
    "endpoint": "/v1/pins/search",
    "credits_charged": 4,
    "cached": true,
    "took_ms": 1
  }
}

Response Fields

Normalized Pinterest visual pins & dominant palette summary.

Field	Type	Sample / Notes
`code`	integer	Example: 0
`provider`	string	Example: https://pindataapi.com
`status`	string	Example: ok
`msg`	string	Example: success
`data`	object
`query`	string
`count`	integer
`next_cursor`	stringnull
`dominant_palette_summary`	array of string
`pins`	array of NormalizedPin
`pin_id`	string
`numeric_id`	stringnull
`title`	string
`description`	stringnull
`alt_text`	stringnull
`dominant_color`	string	Example: #C9B096
`palette_hex`	array of string
`image_url`	string
`thumbnail_url`	stringnull
`width`	integer	Example: 1080
`height`	integer	Example: 1620
`aspect_ratio`	string	Example: 2:3
`saves_count`	integer
`comments_count`	integer
`reactions_count`	integer
`is_shoppable`	boolean
`merchant_domain`	stringnull	Example: garmentory.com
`outbound_url`	stringnull
`pin_url`	string
`creator`	object
`board`	object
`meta`	ResponseMeta
`request_id`	string
`endpoint`	string
`credits_charged`	integer
`cached`	boolean
`took_ms`	integer

Status Codes

200: Normalized Pinterest visual pins & dominant palette summary.
401
402
429