Pinterest Pins
Pinterest Pins are public visual posts with titles, descriptions, creator details, image or video references, categories, hashtags, and visible engagement. These records support selected-content archiving, creative and topic research, attribution, and collection-time comparison.
Features
- Direct and short Pin URLsProcess one or more public Pinterest /pin/{id} URLs or pin.it short links while keeping collection scoped to the submitted Pins.
- Connected content and creator fieldsReturn Pin title and text beside the source URL, public creator identity, profile URL, and normalized image or video references.
- Visible metrics with observation timeKeep available like and comment counts plus creator follower count with collected_at so mutable public values have a clear snapshot time.
- Pin classification contextPreserve available post_type, categories, and hashtags in extra for format and topic analysis without flattening them into the Pin text.
Parameters
| Parameters | Required | Description |
|---|---|---|
urls | Required | Required list of public Pinterest /pin/{id} URLs or pin.it short links. Other Pinterest paths and non-Pinterest hosts are rejected. |
How to Use
Submit the exact public Pins you need, track the asynchronous task, and read normalized Pin records with cursor pagination.
- Prepare one or more public Pinterest /pin/{id} URLs or pin.it short links.
- Submit the links as urls to /v1/pinterest/pins and capture task_id.
- Poll /v1/tasks/{task_id} until processing succeeds or returns a failure.
- Read data.results.items, then request the next page with next_cursor while has_more is true.
curl -X POST "https://api.socq.ai/v1/pinterest/pins" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.pinterest.com/pin/123456789/"]}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueBest Use Cases
- Selected Pin archiving: Preserve Pin IDs, source URLs, titles, text, creator fields, media references, and publication time for a defined URL list.
- Creative and topic review: Use media type, post_type, categories, hashtags, titles, and text to compare formats and themes across selected Pins.
- Collection-time signal comparison: Compare visible like and comment counts together with creator follower context, using collected_at to anchor each observation.
Pro Tips
- Use a public /pin/{id} URL or pin.it link for every item; profile, search, ideas, and other Pinterest paths do not satisfy this endpoint's input rule.
- Deduplicate returned id values when direct and shortened links may resolve to the same Pin.
- Treat media, created_at, categories, hashtags, post_type, and individual metrics as optional fields because a public Pin may not expose each value.
- Store collected_at beside visible metrics so later runs can be interpreted as separate collection-time snapshots.
Related APIs
Use these APIs when you need a different type of public Pinterest data.
- Pinterest User Pins API — Discover public Pins from profile URLs with a per-profile limit, normalized content, creator, media, 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.