{
  "openapi": "3.0.1",
  "info": {
    "title": "Pinterest Scraper — Pins, Boards, Profiles & Images",
    "description": "Pinterest scraper for pins, boards and user profiles. Search by keyword, paste pin URLs, or look up accounts by username for followers, pin and board counts, bio and website. Images, outbound links and engagement stats as clean JSON/CSV, no account or Pinterest API key needed.",
    "version": "1.0",
    "x-build-id": "EdhCTqI7brDv8SRsW"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sian.agency~pinterest-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sian.agency-pinterest-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/sian.agency~pinterest-scraper/runs": {
      "post": {
        "operationId": "runs-sync-sian.agency-pinterest-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/sian.agency~pinterest-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-sian.agency-pinterest-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "scrapeMode": {
            "title": "🧭 Scrape Mode",
            "enum": [
              "overview",
              "detail",
              "userProfile"
            ],
            "type": "string",
            "description": "🧭 **How much data, and of what:**\n\n- **Overview** (cheapest): search pins by query or search URL → image, link, domain, board, pinner, alt-text.\n- **Detail**: paste pin URLs or IDs → adds saves, repins, comments, shares, hashtags and every image size per pin.\n- **User Profile**: look up accounts by username → followers, pin and board counts, bio, website, monthly views. Boards and created pins optional.",
            "default": "overview"
          },
          "searchMode": {
            "title": "🎯 Input Type",
            "enum": [
              "byQuery",
              "bySearchUrl",
              "byPinUrl"
            ],
            "type": "string",
            "description": "🎯 **How Overview finds pins:**\n\n- **By Query**: type one or more search terms (e.g. `home office desk`).\n- **By Search URL**: paste a Pinterest `/search/...` URL (filters in the URL carry through).\n\nDetail mode always uses the pin URLs below, whatever is selected here.",
            "default": "byQuery"
          },
          "queries": {
            "title": "🔎 Search Queries",
            "type": "array",
            "description": "🔎 **SEARCH BY KEYWORD:** One or more search terms — each is run as a Pinterest search.\n\n💡 **TIP:** Click \"Bulk edit\" to paste many queries, one per line.\n\nExample: `minimalist desk`, `home office`, `kitchen pantry organization`",
            "default": [
              "home office desk"
            ],
            "items": {
              "type": "string"
            }
          },
          "scope": {
            "title": "🗂️ Search Scope",
            "enum": [
              "pins",
              "products",
              "videos",
              "boards",
              "users"
            ],
            "type": "string",
            "description": "🗂️ **What the query searches**, like Pinterest's own search tabs:\n\n- **Pins** (default) and **Videos**: pin rows.\n- **Products**: shopping pins only, with price, currency and stock.\n- **Boards**: one row per board (name, URL, pin count, owner).\n- **Users**: one row per account (followers, pin and board counts). For bio, website and monthly views, use User Profile mode.\n\nBoards and Users work in Overview mode.",
            "default": "pins"
          },
          "searchUrls": {
            "title": "🔗 Pinterest Search URLs",
            "type": "array",
            "description": "🔗 **PASTE SEARCH URLS:** One or more `https://www.pinterest.com/search/...` URLs. Any faceted filters in the URL (color, price band, domain) carry through.\n\n💡 **TIP:** Open a search on pinterest.com, set your filters, then copy the address-bar URL.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "pinUrls": {
            "title": "📌 Pin URLs or IDs (Detail mode)",
            "type": "array",
            "description": "📌 **PINS TO ENRICH (Detail mode):** Paste pin URLs (`https://www.pinterest.com/pin/<id>/`) or bare numeric pin IDs to get full engagement stats for each.\n\nPinterest no longer shows real pin IDs in search results, so Detail can't enrich searched pins. To collect pin URLs in bulk, run User Profile mode with Include Created Pins.\n\n💡 **TIP:** Click \"Bulk edit\" to paste many at once, one per line.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "usernames": {
            "title": "👤 Usernames or Profile URLs (User Profile mode)",
            "type": "array",
            "description": "👤 **PROFILE LOOKUP (User Profile only):** Pinterest handles (`nasa`, `@ikeausa`) or profile URLs (`https://www.pinterest.com/nasa/`). One profile row per account.\n\nA username that doesn't exist comes back as a not-found row, and you aren't charged for it.\n\n💡 **TIP:** Click \"Bulk edit\" to paste many at once, one per line.",
            "items": {
              "type": "string"
            }
          },
          "includeBoards": {
            "title": "🗂️ Include Boards (User Profile mode)",
            "type": "boolean",
            "description": "🗂️ Add the account's public boards to each profile row: name, URL, description, pin and follower counts, cover image. No extra charge. Up to 25 boards per page, paged up to `Max Search Pages`.",
            "default": false
          },
          "includePins": {
            "title": "📌 Include Created Pins (User Profile mode)",
            "type": "boolean",
            "description": "📌 Also save the pins each account created (its \"Created\" tab), newest first. Each pin is its own row, billed at the overview pin price.",
            "default": false
          },
          "maxPinsPerUser": {
            "title": "🔢 Max Pins Per Account (User Profile mode)",
            "minimum": 1,
            "type": "integer",
            "description": "🔢 How many created pins to save per account when **Include Created Pins** is on. The run-wide `Max Results Per Run` cap still applies.",
            "default": 25
          },
          "maxResults": {
            "title": "🔢 Max Results Per Run",
            "minimum": 1,
            "type": "integer",
            "description": "🔢 **Cap the number of rows** saved in this run (pins, or profiles plus their pins).\n\n- **FREE users:** up to 25 per run\n- **PAID users:** unlimited\n\nPay-per-result: you only pay for the rows actually returned.",
            "default": 100
          },
          "maxPages": {
            "title": "📄 Max Search Pages",
            "minimum": 1,
            "type": "integer",
            "description": "📄 **How many result pages to paginate** per query/URL (each page ≈ 18–25 pins). Stops early when `Max Results Per Run` is reached or Pinterest runs out of results.",
            "default": 10
          },
          "useProxy": {
            "title": "🛡️ Use Residential Proxy (optional)",
            "type": "boolean",
            "description": "🛡️ **Off by default.** Pinterest data is fetched directly and reliably without a proxy. Enable this only if you run very high volume and hit a rate-limit — it routes requests through a US residential network for extra resilience.",
            "default": false
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}