Pinterest Search API

Pinterest Search

Features

• Query-based Pin discoveryAccept one non-empty text query and a results_limit from 1 through 2,000 to request a bounded collection of public Pin records.
• Normalized Pin, creator, and media recordsReturn Pin IDs, URLs, titles, text, public creator fields, and image or video references in a consistent result shape.
• Taxonomy and visible signal contextKeep available categories, hashtags, Pin type, source metadata, visible like, comment, and creator follower counts, publication time, collection time, and submitted query context.

Parameters

How to Use

Submit a Pinterest text query with a result limit, track the asynchronous task, and read normalized Pins with cursor pagination.

1. Prepare a non-empty text query and choose a results_limit from 1 through 2,000.
2. POST query and results_limit to /v1/pinterest/search, then store the returned task_id.
3. Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
4. Read data.results.items and request the returned next_cursor while has_more remains true.

curl -X POST "https://api.socq.ai/v1/pinterest/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"home office ideas","results_limit":100}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Best Use Cases

• Topic-driven Pin datasets: Use a defined query with Pin IDs, source URLs, titles, text, media references, and discovery_input to build a traceable topic collection.
• Visual and taxonomy research: Compare images or videos, post_type, categories, hashtags, titles, and descriptions to examine formats and themes within query results.
• Creator and visible signal comparison: Combine public creator fields with like, comment, and follower counts plus collected_at to compare observed result context across query collections.

Pro Tips

• Submit a non-empty query after removing accidental surrounding whitespace, and keep results_limit between 1 and 2,000 to satisfy input validation.
• Follow next_cursor until has_more is false when the stored results span more than the first 50-item response page.
• Retain extra.discovery_input and collected_at so each Pin remains tied to the submitted keyword and observation time.
• Handle title, text, author details, media, created_at, categories, hashtags, source, and individual metrics as optional fields instead of treating missing values as request failures.

Related APIs