Pinterest User Pins
Pinterest User Pins are public visual posts associated with a profile and represented by titles, descriptions, creator details, media references, categories, hashtags, timestamps, and visible engagement. These content and observation fields support profile collection archiving, visual-topic research, source attribution, and collection-time comparison.
Features
- Profile-based Pin discoveryAccept one or more public Pinterest profile URLs and return Pin records associated with each submitted profile rather than profile metadata.
- Per-profile collection depthApply results_limit separately to every profile URL, with a default of 100 and an accepted range from 1 through 2,000.
- Normalized Pin, author, and media recordsReturn Pin identifiers, URLs, titles, text, public author fields, and image or video references in a consistent result shape.
- Engagement and source contextKeep visible like, comment, and creator follower counts with publication time, collected_at, classification fields, and discovery_input when available.
Parameters
| Parameters | Required | Description |
|---|---|---|
urls | Required | Required list of public HTTP or HTTPS Pinterest profile URLs with exactly one non-reserved path segment; Pin, search, ideas, and pin.it URLs are rejected. |
results_limit | Optional | Maximum Pins requested for each profile URL; defaults to 100 and accepts integers from 1 through 2,000. |
How to Use
Submit public Pinterest profile URLs with a per-profile result limit, track the asynchronous task, and read normalized Pins with cursor pagination.
- Prepare one or more public Pinterest profile URLs with a single profile path segment.
- POST urls and an optional results_limit to /v1/pinterest/user-pins, then store the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
- Read data.results.items and request the returned next_cursor while has_more remains true.
curl -X POST "https://api.socq.ai/v1/pinterest/user-pins" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.pinterest.com/example/"],"results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueBest Use Cases
- Public profile Pin archiving: Preserve Pin IDs, source URLs, titles, text, author fields, media references, timestamps, and discovery_input for defined profile URLs.
- Visual and taxonomy research: Use media type, post_type, categories, hashtags, titles, and text to examine recurring formats and themes within selected public profiles.
- Cross-profile signal comparison: Compare visible like and comment counts with creator follower context across profile collections, using collected_at to anchor each observation.
Pro Tips
- Submit a public Pinterest profile URL with exactly one profile path segment; Pin links, pin.it short links, search pages, and deeper paths fail profile validation.
- Calculate requested depth and the pre-request credit estimate as the number of urls multiplied by results_limit because the limit applies separately to each profile.
- Store discovery_input and collected_at with every Pin so downstream datasets retain the submitted profile and observation time.
- Treat media, created_at, categories, hashtags, source, author details, and individual metrics as optional, and do not infer whether a Pin was created or saved when no classification is returned.
Related APIs
Use these APIs when you need a different type of public Pinterest data.
- Pinterest Pins API — Resolve public Pin URLs into normalized content, creator, media, taxonomy, timestamps, and visible metrics.
- Pinterest Profiles API — Collect public profile identity, bio, image, website, visible account counts, and collection context from profile URLs.
- Pinterest Search API — Search public Pins by text query with a result limit, returning normalized content, creator, media, taxonomy, timestamps, and visible metrics.