SocQ의 첫 Pinterest 엔드포인트는 프로필, 개별 핀, 사용자의 핀, 검색 결과를 읽었습니다. 2026-11-17에 출시된 3개의 엔드포인트는 다른 수준인 보드와 토픽을 다룹니다. 보드는 브랜드나 크리에이터가 아이디어를 어떻게 정리하는지 보여 주고, 토픽은 아이디어를 몇 명이 검색하는지와 그 아래에 어떤 세부 아이디어가 있는지 보여 줍니다.
이 가이드에서는 새 엔드포인트별로 반환 데이터, 요청 형식, 가격, 그리고 세 엔드포인트를 함께 쓰는 방법을 설명합니다. Pinterest 데이터 제공업체 전반을 비교하고 있다면 Pinterest 스크래퍼 API 베스트 7을 참고하세요.
빠른 답변:
urls에 Pinterest 프로필, 보드, 아이디어 페이지 URL을 담아Authorization: Bearer $SOCQ_API_KEY와 함께POST /v1/pinterest/user-boards,/board,/topic중 하나로 보내세요.status가succeeded가 될 때까지GET /v1/tasks/{task_id}를 폴링한 다음data.results.items를 읽습니다. 세 엔드포인트 모두 결과당 0.5크레딧(크레딧당 $0.005 기준 $0.0025)이며 기본 요금은 없습니다.
새로운 Pinterest 엔드포인트 3종
| 엔드포인트 | 반환 데이터 | 입력 | 가격 |
|---|---|---|---|
| User Boards | 프로필의 공개 보드와 이름, 설명, 커버, 소유자, 생성일, 핀·팔로워·섹션·공동 작업자 수 | 프로필 URL | 보드당 0.5크레딧($0.0025) |
| Board Pins | 보드에 담긴 핀을 보드 순서대로, 설명, 저장한 사용자, 원본 크기 이미지, 핀 링크와 함께 반환 | 보드 URL | 핀당 0.5크레딧($0.0025) |
| Topic | 토픽의 월간 검색 수와 Pinterest가 제안하는 하위 토픽 | 아이디어 페이지 URL | 토픽당 0.5크레딧($0.0025) |
Pinterest User Boards: 프로필 점검하기
Pinterest User Boards API는 Pinterest 프로필의 공개 보드를 모두 나열합니다. 각 보드에는 이름, 설명, 커버 이미지, 소유자, 생성일, 핀·팔로워·섹션·공동 작업자 수가 포함되며, 다른 계정이 핀을 추가할 수 있는 보드에는 is_collaborative 플래그가 붙습니다. 경쟁사의 Pinterest를 점검하거나 토픽별로 크리에이터 후보를 추릴 때 가장 먼저 호출하는 엔드포인트입니다. 수치를 보면 계정이 어떤 주제에 투자하는지, 사람들이 실제로 팔로우하는 컬렉션은 무엇인지 알 수 있습니다.
curl -X POST "https://api.socq.ai/v1/pinterest/user-boards" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://www.pinterest.com/marthastewart/"],
"results_limit": 25
}'
https://www.pinterest.com/username/ 같은 프로필 URL을 사용하세요. results_limit은 프로필마다 적용되며 기본값은 25이고 1부터 500까지 받습니다. 보드 수치는 metrics 아래의 pins_count, followers_count, sections_count, collaborators_count에 있습니다. User Boards 문서를 참고하세요.
Pinterest Board Pins: 보드에 담긴 핀 수집하기
Pinterest Board Pins API는 보드 안의 핀을 보드에 표시되는 순서대로 반환합니다. 각 핀에는 제목이나 설명, 핀을 저장한 계정, 원본 크기 이미지(media 아래에 썸네일과 크기 정보 포함), 핀 URL이 들어 있습니다. 내 분야의 큐레이션 보드에서 참고 이미지를 모으거나, 경쟁사가 시즌 보드에 계속 추가하는 핀을 추적하거나, 무드보드 데이터셋을 한 번에 구축할 때 사용하세요.
curl -X POST "https://api.socq.ai/v1/pinterest/board" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://www.pinterest.com/lizmrodgers/moms-night/"],
"results_limit": 50
}'
보드 URL은 /{username}/{board}/ 형식을 사용하세요. results_limit은 보드마다 적용되며 기본값은 50이고 1부터 1,000까지 받습니다. Board Pins 문서를 참고하세요.
Pinterest Topic: Pinterest 키워드 리서치
Pinterest Topic API는 콘텐츠를 만들기 전에 토픽의 규모를 가늠해 줍니다. 아이디어 페이지마다 Pinterest가 보고하는 월간 검색 수(search_count)와 그 아래에 제안하는 하위 토픽(related_topics, 각각 이름, 짧은 라벨, 자체 아이디어 페이지 URL 포함)을 얻을 수 있습니다. 하위 토픽에는 사람들이 주요 아이디어와 함께 조합하는 스타일, 상황, 소재 등이 있습니다.
curl -X POST "https://api.socq.ai/v1/pinterest/topic" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://www.pinterest.com/ideas/home-decor/935249274030/"]
}'
아이디어 페이지 URL은 /ideas/{topic}/{id}/ 형식을 사용하세요. 토픽마다 한 행을 반환합니다. 모든 하위 토픽에 자체 URL이 있으므로, 이 URL을 같은 엔드포인트에 다시 넣어 롱테일 주제 간 수요를 비교할 수 있습니다. Topic 문서를 참고하세요.
세 엔드포인트를 함께 쓰는 방법
일반적인 경쟁사 또는 니치 분석은 세 엔드포인트를 다음과 같이 연결합니다.
- 경쟁사 프로필에 User Boards를 실행해 팔로워와 핀이 가장 많은 보드를 확인합니다.
- 중요한 보드에 Board Pins를 실행해 그 안의 이미지와 설명을 수집합니다.
- 해당 주제의 아이디어 페이지에 Topic을 실행해 월간 검색 수요를 확인하고 세부 주제를 찾습니다.
개별 핀, 사용자 본인의 핀, 키워드 검색 결과에는 기존 Pins, User Pins, Search 엔드포인트를 사용하세요. 모든 Pinterest 엔드포인트는 Pinterest 플랫폼 페이지에 있습니다.
인증과 비동기 작업 흐름
모든 요청에는 API 키와 JSON 콘텐츠 유형이 포함됩니다.
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
제출 호출마다 백그라운드 작업이 시작됩니다.
submit -> task_id -> queued -> running -> succeeded
\-> failed
제출 응답은 data.task_id와 data.status를 반환합니다. 같은 키로 작업을 폴링하세요.
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
작업이 queued, running, failed 상태인 동안에는 응답에 작업 메타데이터만 들어 있으며, failed이면 error_message를 확인하세요. succeeded가 되면 같은 응답의 data.results.items에 정규화된 레코드의 첫 페이지가 포함됩니다. limit의 기본값은 50이고 최대 500까지 지정할 수 있습니다. has_more가 true이면 results.next_cursor를 cursor로 넘겨 다음 페이지를 읽습니다. 몇 개의 열만 필요할 때는 fields에 쉼표로 구분한 필드나 점 경로를 최대 50개까지 지정할 수 있습니다. 예를 들어 보드에는 name,metrics.followers_count를 쓸 수 있습니다.
클라이언트 쪽 타임아웃은 작업을 취소하지 않습니다. 다시 제출해 중복 비용을 내지 말고 같은 task_id로 조회를 이어가세요. 폴링을 생략하려면 제출 본문에 callback_url을 추가하세요. 작업이 끝나면 SocQ가 작업 요약을 담은 POST를 한 번 보내며, 레코드는 작업 엔드포인트에서 읽습니다.
일반적인 작업 비용
- 프로필 하나의 보드 25개 조회: 25 × 0.5 = 12.5크레딧, $0.0625.
- 보드 하나에서 핀 1,000개 수집: 500크레딧, $2.50.
- 토픽 20개 확인: 10크레딧, $0.05.
results_limit은 프로필이나 보드마다 적용되므로, URL을 여러 개 담은 요청은 URL마다 그 수만큼 행을 반환할 수 있습니다. URL 수를 고려해 한도를 정하세요.
자주 묻는 질문(FAQ)
User Boards는 비공개 보드나 비밀 보드도 반환하나요?
아니요. 프로필의 공개 보드만 나열합니다.
Topic의 검색 수는 무엇을 뜻하나요?
search_count는 Pinterest가 해당 아이디어 페이지에 대해 보고하는 월간 검색 수입니다. updated_at은 Pinterest가 토픽을 마지막으로 갱신한 시각입니다.
여러 보드의 핀을 한 요청으로 가져올 수 있나요?
네. urls에 보드 URL을 여러 개 넣으세요. results_limit은 보드마다 따로 적용되며, 반환된 핀마다 0.5크레딧이 듭니다.
보드가 비어 있어도 비용이 드나요?
기본 요금이 없으므로 반환된 보드, 핀, 토픽에 대해서만 비용을 냅니다.
Pinterest 가격은 어디에 나와 있나요?
각 랜딩 페이지에 해당 요금이 표시되며, 요금 페이지에서 모든 SocQ API의 현재 크레딧 요금을 확인할 수 있습니다.
PINTEREST API
공개 Pinterest URL로 워크플로를 테스트하세요
공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.
Pinterest API 살펴보기