Pinterest API search: what v5 allows, and a keyword script

export TOOLZERHUB_API_KEY=your_key
curl -G -H "x-api-key: $TOOLZERHUB_API_KEY" \
  --data-urlencode "query=kitchen ideas" \
  "https://api.toolzerhub.com/v1/pinterest/search/pins"

{
  "data": {
    "results": [
      {
        "id": "e1_AfqPShz3R431sNW1uDn-eJrr22p4ZLWBaUku450zFRi3SJcINS-rdw",
        "type": "pin",
        "title": "Cozy Modern Farmhouse Kitchen Ideas",
        "description": "Create a warm and inviting kitchen with elegant sage-green cabinets, ...",
        "link": null,
        "domain": "Uploaded by user",
        "created_at": "Thu, 01 Oct 2026 05:48:30 +0000",
        "reaction_counts": {"1": 13},
        "auto_alt_text": "a kitchen filled with lots of green cabinets and counter top space next to a window",
        "images": {
          "orig": {"width": 672, "height": 795, "url": "https://i.pinimg.com/originals/69/06/60/690660fb8a0f21dfdf4aaa54d3223e1e.jpg"}
        },
        "videos": null,
        "pinner": {"username": "…", "follower_count": 51},
        "board": {"id": "1109293020658371701", "name": "cozy kitchen home decor", "url": "/…/cozy-kitchen-home-decor/"}
      }
    ],
    "bookmark": "Y2JVSG81V2sxcmNHRlpWM1J5VFVad1ZsWlVWbFJXTVVZMldWVlZOV0pIU2ta..."
  }
}

import argparse
import csv
import os
import re
import sys
import time
from email.utils import parsedate_to_datetime
from pathlib import Path

import requests

URL = "https://api.toolzerhub.com/v1/pinterest/search/pins"
HEADERS = {"x-api-key": os.environ.get("TOOLZERHUB_API_KEY", "")}
FIELDS = ["pin_key", "title", "description", "image_url", "width", "height", "video_url",
          "link", "domain", "reactions", "created", "pinner", "board", "board_url", "alt_text"]


def search(query, scope, bookmark, tries=3):
    # 429, 5xx and dropped connections are retried; failed calls cost no credits.
    params = {"query": query, "scope": scope, **({"bookmark": bookmark} if bookmark else {})}
    for attempt in range(tries):
        last = attempt == tries - 1
        try:
            r = requests.get(URL, headers=HEADERS, params=params, timeout=120)
        except requests.RequestException:
            if last:
                raise
            time.sleep(10 * (attempt + 1))
            continue
        if r.status_code in (429, 500, 502, 503, 504) and not last:
            time.sleep(10 * (attempt + 1))
            continue
        if r.status_code == 401:
            sys.exit("the API key was rejected: check TOOLZERHUB_API_KEY")
        if r.status_code == 402:
            sys.exit("out of credits: the CSV keeps the pages written so far")
        r.raise_for_status()
        return r.json().get("data") or {}


def row(pin):
    image = (pin.get("images") or {}).get("orig") or {}
    video = ((pin.get("videos") or {}).get("video_list") or {}).get("V_HLSV4") or {}
    board = pin.get("board") or {}
    try:
        created = parsedate_to_datetime(pin["created_at"]).date().isoformat()
    except (KeyError, TypeError, ValueError):
        created = ""
    return {
        "pin_key": pin["id"],  # an opaque key, not the number in a /pin/ URL
        "title": (pin.get("title") or pin.get("grid_title") or "").strip(),
        "description": " ".join((pin.get("description") or "").split()),
        "image_url": image.get("url"), "width": image.get("width"), "height": image.get("height"),
        "video_url": video.get("url") or "",  # an HLS playlist (.m3u8)
        "link": pin.get("link") or "", "domain": pin.get("domain") or "",
        "reactions": sum((pin.get("reaction_counts") or {}).values()),
        "created": created,
        "pinner": (pin.get("pinner") or {}).get("username"), "board": board.get("name"),
        "board_url": "https://www.pinterest.com" + board["url"] if board.get("url") else "",
        "alt_text": pin.get("auto_alt_text") or "",
    }


def download(rows, folder):
    # Files are numbered in CSV row order.
    Path(folder).mkdir(parents=True, exist_ok=True)
    saved = failed = 0
    for i, r in enumerate(rows, 1):
        if not r["image_url"]:
            continue
        path = Path(folder) / f"{i:04d}{Path(r['image_url']).suffix or '.jpg'}"
        try:
            resp = requests.get(r["image_url"], timeout=60)
            resp.raise_for_status()
            path.write_bytes(resp.content)
            saved += 1
        except requests.RequestException:
            failed += 1
    return saved, failed


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("query")
    ap.add_argument("--pages", type=int, default=10)
    ap.add_argument("--scope", choices=["pins", "videos"], default="pins")
    ap.add_argument("--out")
    ap.add_argument("--images", help="folder to save the original images into")
    a = ap.parse_args()
    if not HEADERS["x-api-key"]:
        sys.exit("set TOOLZERHUB_API_KEY first")
    out = a.out or "pinterest_" + re.sub(r"\W+", "_", a.query).strip("_") + ".csv"
    seen, rows, repeats, pages, bookmark = set(), [], 0, 0, None
    with open(out, "w", newline="", encoding="utf-8-sig") as f:  # -sig: Excel reads UTF-8
        writer = csv.DictWriter(f, fieldnames=FIELDS)
        writer.writeheader()
        for _ in range(a.pages):
            data = search(a.query, a.scope, bookmark)
            pages += 1
            for pin in data.get("results") or []:
                if pin.get("type") != "pin":  # skip any non-pin module in the results
                    continue
                if pin["id"] in seen:
                    repeats += 1
                    continue
                seen.add(pin["id"])
                rows.append(row(pin))
                writer.writerow(rows[-1])
            bookmark = data.get("bookmark")
            if not bookmark or bookmark == "-end-":
                break
    print(f"{len(rows)} pins from {pages} page(s) written to {out}, {repeats} repeats skipped")
    if a.images:
        saved, failed = download(rows, a.images)
        print(f"{saved} images saved to {a.images}/, {failed} failed")


if __name__ == "__main__":
    main()

export TOOLZERHUB_API_KEY=your_key
python pinterest_search.py "kitchen ideas" --pages 40 --out deep_kitchen.csv
python pinterest_search.py "wedding cake" --scope videos
python pinterest_search.py "minimalist tattoo" --images tattoo_images

806 pins from 40 page(s) written to deep_kitchen.csv, 184 repeats skipped