Pinterest · Social Dash Scraper Docs

Visual discovery API

Live private service · production acceptance passed

Search public pins, retrieve pin details, browse user boards, and read board pins.

Four authenticated endpoints for public Pinterest discovery and metadata. Follow source pagination and choose full or compact responses. Availability depends on Pinterest’s logged-out access; private and restricted resources fail explicitly.

Base URLhttp://localhost:3014

Local development example. Replace with your service origin.

Search Pinterest pins

GET/v1/pinterest/search

Discover public pins for a keyword. Retrieves one page with a requested page size of 25; Pinterest controls the actual result count and ranking. Pass cursor to continue. Full records retain available image, destination, board, author, counter and media fields. Trimmed pins contain id, url, description, created_at, pinner and images when supplied.

Query parameters

Field	Type	Description
query	string	Required keyword, 1–500 characters after trimming.
cursor	string	Optional source bookmark returned by the previous response. Reuse with the same query, handle, or board. Null means end of results unless coverage warns pagination_unavailable. Source cursors can expire. Maximum 16,384 characters.
trim	string	Optional true or false (default false). True selects the documented compact fields; false preserves the public source record and nested extensions. Missing source fields remain absent.

Request cURL

export BASE_URL="http://localhost:3014"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/pinterest/search" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "query=synthetic recipes"

Response fields

Field	Type	Description
success	boolean	True when usable supported data was retrieved.
status	string	success, partial, failed, or challenged. Partial results carry coverage warnings.
requestId	string	Opaque operation identifier for correlation.
sourceUrl	string	Canonical public source page. This field can contain the requested search query.
fetchedAt	string	UTC retrieval time. Every call makes fresh upstream requests; Pinterest may serve its own cached data.
coverage	object	Completeness of this supported response page, not the entire account or search corpus. Check restricted_records, malformed_records, record_limit, pagination_unavailable, and missing_pin_counts. Some pin pages omit share/reaction counts; these remain absent with explicit partial coverage.
accounting	object	Upstream attempts, total decoded response bytes, and elapsed milliseconds. No competitor credits are synthesized.
pins	array	Ordered public pin records. Source nulls and nested attributes are preserved. Maximum 100 records; over-limit or malformed results produce explicit partial coverage.
cursor	string \| null	Optional source bookmark returned by the previous response. Reuse with the same query, handle, or board. Null means end of results unless coverage warns pagination_unavailable. Source cursors can expire. Maximum 16,384 characters.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "success": true,
  "status": "success",
  "requestId": "synthetic-pinterest-request",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_resource",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 1200,
    "durationMs": 120
  },
  "pins": [
    {
      "id": "123456789",
      "type": "pin",
      "title": "Synthetic recipe",
      "description": "",
      "created_at": "Thu, 10 Sep 2026 00:00:00 +0000",
      "images": {
        "orig": {
          "url": "https://i.pinimg.com/synthetic.jpg",
          "width": 800,
          "height": 600
        }
      },
      "pinner": {
        "id": "456",
        "username": "example",
        "follower_count": 0
      },
      "board": {
        "id": "777",
        "url": "/example/recipes/"
      },
      "videos": null,
      "sourceExtension": {
        "unknown": null
      },
      "url": "https://www.pinterest.com/pin/123456789/"
    }
  ],
  "cursor": "synthetic-next-page",
  "sourceUrl": "https://www.pinterest.com/search/pins/?q=synthetic+recipes"
}

Get a Pinterest pin

GET/v1/pinterest/pin

Read a public pin’s page data without executing page scripts. Full responses expose Pinterest’s camelCase fields at the top level, preserving nested media and author data. imageSpec_orig aliases images_orig when needed. Trimmed fields: entityId, seoAltText, originPinner, pinner, imageSpec_orig, description, shareCount, nativeCreator, createdAt, repinCount and totalReactionCount. Counts are never guessed; missing required pin fields fail explicitly. cache_max_age is unsupported.

Query parameters

Field	Type	Description
url	string	Required HTTPS pinterest.com or www.pinterest.com pin URL (/pin/<numeric-id>/). No credentials, explicit ports, short links, regional domains or encoded path segments. Tracking query parameters and fragments are removed.
trim	string	Optional true or false (default false). True selects the documented compact fields; false preserves the public source record and nested extensions. Missing source fields remain absent.

Request cURL

export BASE_URL="http://localhost:3014"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/pinterest/pin" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "url=https://www.pinterest.com/pin/123456789/"

Response fields

Field	Type	Description
entityId	string	Always included.
description	string \| null	Always included.
pinner	object \| null	Always included.
imageSpec_orig	object	Always included.
createdAt	string	Always included.
repinCount	number	Always included.
shareCount	number	Optional.
totalReactionCount	number	Optional.
success	boolean	True when usable supported data was retrieved.
status	string	success, partial, failed, or challenged. Partial results carry coverage warnings.
requestId	string	Opaque operation identifier for correlation.
sourceUrl	string	Canonical public source page. This field can contain the requested search query.
fetchedAt	string	UTC retrieval time. Every call makes fresh upstream requests; Pinterest may serve its own cached data.
coverage	object	Completeness of this supported response page, not the entire account or search corpus. Check restricted_records, malformed_records, record_limit, pagination_unavailable, and missing_pin_counts. Some pin pages omit share/reaction counts; these remain absent with explicit partial coverage.
accounting	object	Upstream attempts, total decoded response bytes, and elapsed milliseconds. No competitor credits are synthesized.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "success": true,
  "status": "success",
  "requestId": "synthetic-pinterest-request",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_page",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 1200,
    "durationMs": 120
  },
  "entityId": "123456789",
  "id": "UGluOjEyMzQ1Njc4OQ==",
  "description": "Synthetic recipe",
  "seoAltText": "Synthetic illustration",
  "createdAt": "Thu, 10 Sep 2026 00:00:00 +0000",
  "pinner": {
    "entityId": "456",
    "username": "example",
    "followerCount": 0
  },
  "originPinner": null,
  "nativeCreator": null,
  "images_orig": {
    "url": "https://i.pinimg.com/synthetic.jpg",
    "width": 800,
    "height": 600
  },
  "shareCount": 0,
  "repinCount": 2,
  "totalReactionCount": 0,
  "videos": null,
  "sourceExtension": {
    "unknown": null
  },
  "imageSpec_orig": {
    "url": "https://i.pinimg.com/synthetic.jpg",
    "width": 800,
    "height": 600
  },
  "sourceUrl": "https://www.pinterest.com/pin/123456789/"
}

Get a user’s boards

GET/v1/pinterest/user/boards

List one page of public boards, preserving order, source counts and nested metadata. Requests 25 boards. Cursor input is supported as an extension to the competitor’s documented request contract. Trimmed boards retain id, url, description, follower_count, pin_count, name, image_cover_hd_url and created_at when present. Pinterest does not supply every field for every board; absent timestamps and cover fields are not invented.

Query parameters

Field	Type	Description
handle	string	Required Pinterest username, 1–60 letters, digits or underscores; normalized to lowercase.
cursor	string	Optional source bookmark returned by the previous response. Reuse with the same query, handle, or board. Null means end of results unless coverage warns pagination_unavailable. Source cursors can expire. Maximum 16,384 characters.
trim	string	Optional true or false (default false). True selects the documented compact fields; false preserves the public source record and nested extensions. Missing source fields remain absent.

Request cURL

export BASE_URL="http://localhost:3014"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/pinterest/user/boards" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "handle=example"

Response fields

Field	Type	Description
success	boolean	True when usable supported data was retrieved.
status	string	success, partial, failed, or challenged. Partial results carry coverage warnings.
requestId	string	Opaque operation identifier for correlation.
sourceUrl	string	Canonical public source page. This field can contain the requested search query.
fetchedAt	string	UTC retrieval time. Every call makes fresh upstream requests; Pinterest may serve its own cached data.
coverage	object	Completeness of this supported response page, not the entire account or search corpus. Check restricted_records, malformed_records, record_limit, pagination_unavailable, and missing_pin_counts. Some pin pages omit share/reaction counts; these remain absent with explicit partial coverage.
accounting	object	Upstream attempts, total decoded response bytes, and elapsed milliseconds. No competitor credits are synthesized.
boards	array	Ordered public board records with canonical URLs. Maximum 100 records. Nested source fields are preserved by default.
cursor	string \| null	Optional source bookmark returned by the previous response. Reuse with the same query, handle, or board. Null means end of results unless coverage warns pagination_unavailable. Source cursors can expire. Maximum 16,384 characters.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "success": true,
  "status": "success",
  "requestId": "synthetic-pinterest-request",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_resource",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 1200,
    "durationMs": 120
  },
  "boards": [
    {
      "id": "777",
      "type": "board",
      "name": "Synthetic recipes",
      "description": "",
      "url": "https://www.pinterest.com/example/recipes/",
      "owner": {
        "id": "456",
        "username": "example"
      },
      "privacy": "public",
      "pin_count": 2,
      "follower_count": 0,
      "image_cover_hd_url": null,
      "created_at": null,
      "sourceExtension": {
        "unknown": null
      }
    }
  ],
  "cursor": null,
  "sourceUrl": "https://www.pinterest.com/example/"
}

Get pins from a board

GET/v1/pinterest/board

Resolve a public board and retrieve one page of its pins, requesting 25 items. Each returned pin’s board ID must match. All board sections are included where Pinterest supplies them. Pass cursor for the next page. Full records preserve source fields; trim=true uses the same compact pin fields as search. Media files and destination links are never downloaded.

Query parameters

Field	Type	Description
url	string	Required HTTPS pinterest.com or www.pinterest.com board URL (/<handle>/<slug>/). Board slugs currently accept ASCII letters, digits, underscores and hyphens. No credentials, explicit ports, short links, regional domains or encoded path segments. Tracking query parameters and fragments are removed.
cursor	string	Optional source bookmark returned by the previous response. Reuse with the same query, handle, or board. Null means end of results unless coverage warns pagination_unavailable. Source cursors can expire. Maximum 16,384 characters.
trim	string	Optional true or false (default false). True selects the documented compact fields; false preserves the public source record and nested extensions. Missing source fields remain absent.

Request cURL

export BASE_URL="http://localhost:3014"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/pinterest/board" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "url=https://www.pinterest.com/example/recipes/"

Response fields

Field	Type	Description
success	boolean	True when usable supported data was retrieved.
status	string	success, partial, failed, or challenged. Partial results carry coverage warnings.
requestId	string	Opaque operation identifier for correlation.
sourceUrl	string	Canonical public source page. This field can contain the requested search query.
fetchedAt	string	UTC retrieval time. Every call makes fresh upstream requests; Pinterest may serve its own cached data.
coverage	object	Completeness of this supported response page, not the entire account or search corpus. Check restricted_records, malformed_records, record_limit, pagination_unavailable, and missing_pin_counts. Some pin pages omit share/reaction counts; these remain absent with explicit partial coverage.
accounting	object	Upstream attempts, total decoded response bytes, and elapsed milliseconds. No competitor credits are synthesized.
pins	array	Ordered public pin records. Source nulls and nested attributes are preserved. Maximum 100 records; over-limit or malformed results produce explicit partial coverage.
cursor	string \| null	Optional source bookmark returned by the previous response. Reuse with the same query, handle, or board. Null means end of results unless coverage warns pagination_unavailable. Source cursors can expire. Maximum 16,384 characters.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "success": true,
  "status": "success",
  "requestId": "synthetic-pinterest-request",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_resource",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 2,
    "responseBytes": 1200,
    "durationMs": 120
  },
  "pins": [
    {
      "id": "123456789",
      "type": "pin",
      "title": "Synthetic recipe",
      "description": "",
      "created_at": "Thu, 10 Sep 2026 00:00:00 +0000",
      "images": {
        "orig": {
          "url": "https://i.pinimg.com/synthetic.jpg",
          "width": 800,
          "height": 600
        }
      },
      "pinner": {
        "id": "456",
        "username": "example",
        "follower_count": 0
      },
      "board": {
        "id": "777",
        "url": "/example/recipes/"
      },
      "videos": null,
      "sourceExtension": {
        "unknown": null
      },
      "url": "https://www.pinterest.com/pin/123456789/"
    }
  ],
  "cursor": null,
  "sourceUrl": "https://www.pinterest.com/example/recipes/"
}

Coverage & limits

Four concurrent operations; one 20-second deadline per operation.
At most three upstream HTTP attempts, including one shared transient retry. Board retrieval uses two ordinary requests; other operations use one.
At most 4 MiB of combined decoded successful response data, JSON depth 24 and 40,000 parsed JSON nodes.
Lists request 25 records per page and return at most 100. One cursor page per request; no automatic enumeration.
Logged-out HTTPS to www.pinterest.com only. No Pinterest account, cookies, proxy, browser execution, media download or destination visits.
Dedicated PINTEREST_API_KEY in x-api-key. Process health confirms local readiness, not upstream availability.
No result retention, shared database, cache_max_age, competitor credits or customer billing.
Collection completeness applies only to the returned page. Missing optional source fields are omitted; source ordering and null values are retained.

Errors & partial results

HTTP	Code / status	Meaning
200	partial	Some records were restricted, malformed or capped, or pagination was unavailable. Inspect coverage.warnings.
400	invalid_request	Missing, duplicate, unsupported or invalid parameters or URL.
401	unauthorized	Missing or invalid service key.
403	restricted_page	Access-gated pin/board or no usable public records.
404	not_found	Pinterest explicitly reported a missing resource, or the route is unknown.
429	upstream_rate_limited	Pinterest rate limited retrieval.
502	upstream_challenged	Pinterest challenged the request.
502	unsupported_page / upstream_error	Incomplete, changed or mismatched source data, or retrieval failure.
502	response_too_large / payload_too_complex / request_limit	A byte, parsing or request bound was exceeded.
502	unsafe_redirect	Upstream redirected; redirects are not followed.
503	busy	All worker slots are occupied.
504	timeout	The shared deadline expired.