Instagram 릴스 하나를 직접 수집하는 일은 쉽습니다. 하지만 수백 명의 공개 크리에이터를 대상으로 반복 가능한 데이터셋을 만드는 일은 훨씬 어렵습니다. 릴스는 사라질 수 있고, 지표는 계속 바뀌며, 미디어 URL은 만료되고, 게시물마다 화면에 보이는 필드도 다르기 때문입니다.
이 튜토리얼에서는 SocQ Instagram Reels API로 사용자 이름 기준의 공개 릴스를 수집하고, 비동기 작업을 폴링하며, 변하지 않는 엔터티 필드와 지표 스냅샷을 분리해 저장하고, 모니터링이나 분석에 쓸 수 있게 데이터를 준비하는 방법을 설명합니다.
빠른 답변: 공개 사용자 이름과 사용자 이름별
results_limit을POST /v1/instagram/reels에 제출하세요. 반환된task_id를 저장하고, 작업 엔드포인트를 폴링한 뒤data.results.items에서 정규화된 릴스 레코드를 읽으면 됩니다. 현재 이 엔드포인트는 사용자 이름을 받으며 개별 릴스 URL은 받지 않습니다.
Instagram 공식 API와 공개 릴스 API 중 무엇을 쓸까요?
사용자가 지원되는 비즈니스 계정을 승인했고 애플리케이션에서 게시, 인사이트, 댓글 관리 등 권한이 필요한 작업을 해야 한다면 Meta의 공식 Instagram API가 올바른 선택입니다.
공식 API는 임의의 공개 일반 프로필을 수집하는 범용 엔드포인트가 아닙니다. 공식 접근은 계정 유형, 권한, 토큰, 앱 심사, 선택한 Instagram 제품에 따라 달라집니다. 승인 기반 워크플로를 설계하기 전에 최신 Instagram Platform 문서를 확인하세요.
지원되는 공개 읽기 워크플로에는 SocQ를, 계정 작업과 권한이 필요한 인사이트에는 Meta 공식 API를 사용하세요. 공개 데이터 API를 쓴다고 해서 Instagram의 약관, 개인정보 권리, 지식재산권 규정을 무시해도 된다는 뜻은 아닙니다.
Instagram 릴스 작업 제출
현재 엔드포인트는 공개 사용자 이름을 하나 이상 받습니다.
curl -X POST "https://api.socq.ai/v1/instagram/reels" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"usernames": ["natgeo", "instagram"],
"results_limit": 100
}'
제출하기 전에 사용자 이름을 정규화하세요.
- 앞의
@를 제거합니다. - 공백을 다듬습니다.
- 프로필 URL은 입력 계층에서 사용자 이름으로 변환합니다.
- 대소문자를 구분하지 않고 중복을 제거합니다.
- 빈 값은 거부합니다.
results_limit은 사용자 이름별로 요청하는 결과 수를 제한할 뿐이며, 모든 크리에이터가 그만큼의 공개 릴스를 가지고 있다는 보장은 아닙니다.
비동기 작업 폴링
반환된 task_id를 저장하고 폴링하세요.
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queued와 running은 정상 상태로 취급하세요. 짧은 간격으로 반복 폴링하지 말고 지수 백오프를 사용하세요. 작업이 성공하면 data.results.items를 읽습니다. has_more가 true라면 next_cursor로 다음 페이지를 요청하세요.
안정적인 워커는 다음 정보를 저장해야 합니다.
- 배치 ID.
- SocQ 작업 ID.
- 제출한 사용자 이름.
- 제출 시각과 완료 시각.
- 최종 상태와 오류 분류.
- 마지막으로 처리한 결과 커서.
이 상태가 있으면 이미 완료된 수집을 다시 제출하지 않고도 워커가 이어서 작업할 수 있습니다.
릴스 응답 이해하기
정규화된 릴스 레코드는 다음과 같은 모습입니다.
{
"id": "3138424916027781494",
"platform": "instagram",
"resource": "reels",
"type": "reel",
"shortcode": "CtjoC2BNsB2",
"url": "https://www.instagram.com/reel/CtjoC2BNsB2/",
"caption": "A public Instagram Reel.",
"author": {
"id": "123",
"username": "natgeo",
"name": "National Geographic",
"url": "https://www.instagram.com/natgeo"
},
"metrics": {
"likes_count": 21904,
"comments_count": 502,
"views_count": 284110,
"plays_count": 284110
},
"media": [],
"duration_seconds": 42,
"audio": {
"title": "Original audio",
"artist": "natgeo"
},
"hashtags": [],
"mentions": [],
"created_at": "2026-07-08T16:05:00",
"collected_at": "2026-07-19T10:00:00",
"extra": {}
}
엔터티 키로는 id를 우선 사용하고, 없으면 shortcode를 대체로 쓰세요. 추적을 위해 url도 보관하세요. 지표, 미디어, 오디오, 일부 프로필 필드는 제공되지 않을 수 있으므로, 값이 없다고 0이나 빈 문자열로 바꾸지 말고 null을 허용하도록 모델링하세요.
엔터티와 지표 스냅샷을 분리해서 저장하기
릴스의 식별 정보와 지표는 바뀌는 속도가 다릅니다.
엔터티 테이블에는 다음을 저장할 수 있습니다.
reel_id
shortcode
canonical_url
author_id
caption
created_at
duration_seconds
audio
first_seen_at
last_seen_at
스냅샷 테이블에는 다음을 저장할 수 있습니다.
reel_id
collected_at
likes_count
comments_count
views_count
plays_count
이렇게 하면 매일 모니터링해도 릴스 엔터티가 중복 생성되지 않고, 시간에 따른 성장 추이도 보존됩니다.
둘 중 한 스냅샷에 지표가 없다면 성장률을 계산하지 마세요. 숨겨진 수치는 0이 아닙니다. views_count와 plays_count를 모든 소스에서 똑같이 정의한다고 보고 비교하는 것도 피하세요.
증분 릴스 모니터 구축
가장 단순하면서 안정적인 모니터는 다음과 같습니다.
Creator registry
↓
Daily or hourly collection schedule
↓
Async task polling
↓
Schema validation
↓
Upsert Reel entity by id
↓
Append metric snapshot
↓
Alerts and reports
크리에이터마다 다음 순서로 진행하세요.
- 적당한 최근 기간을 수집합니다.
- 가능하면
created_at기준으로 레코드를 정렬합니다. - 이미 본 오래된 레코드를 새로 발견한 것으로 취급하지 않습니다.
- 릴스 ID 기준으로 Upsert합니다.
- 수집이 성공했을 때만 스냅샷을 추가합니다.
- 작업 제출 시점과 별도로 크리에이터의 마지막 성공 실행 시각을 추적합니다.
Instagram 피드는 순위가 매겨지고 소스 가용성도 바뀔 수 있습니다. 이 엔드포인트를 전체 과거 아카이브가 보장되는 것으로 취급하면 안 됩니다.
페이지네이션을 포함한 Python 예제
import time
import requests
BASE = "https://api.socq.ai/v1"
HEADERS = {
"Authorization": f"Bearer {SOCQ_API_KEY}",
"Content-Type": "application/json",
}
created = requests.post(
f"{BASE}/instagram/reels",
headers=HEADERS,
json={"usernames": ["natgeo"], "results_limit": 200},
timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["task_id"]
delay = 2
while True:
response = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
response.raise_for_status()
task = response.json()["data"]
if task["status"] == "succeeded":
break
if task["status"] in {"failed", "cancelled"}:
raise RuntimeError(task)
time.sleep(delay)
delay = min(delay * 1.5, 15)
items = task["results"]["items"]
cursor = task["results"].get("next_cursor")
while cursor:
page = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
params={"limit": 100, "cursor": cursor},
timeout=30,
)
page.raise_for_status()
results = page.json()["data"]["results"]
items.extend(results["items"])
cursor = results.get("next_cursor")
운영 환경에서는 타임아웃, 429, 재시도 가능한 5xx 응답에 대해 횟수를 제한한 재시도를 추가하세요. 오류 분류를 확인하지 않고 실패한 입력을 자동으로 다시 제출하지 마세요.
저장 전에 릴스 데이터 검증하기
권장하는 검사는 다음과 같습니다.
platform은instagram이어야 합니다.resource는reels여야 합니다.id,shortcode,url중 적어도 하나는 있어야 합니다.- 가능한 경우
author.username이 제출한 크리에이터와 일치해야 합니다. - 수치는 음이 아닌 숫자이거나 null이어야 합니다.
created_at과collected_at은 타임스탬프로 파싱되어야 합니다.- 미디어 항목은 영구 자산이 아니라 원본 참조로 취급해야 합니다.
유효하지 않은 레코드는 원본 작업과 검증 오류를 함께 격리 테이블에 보관하세요. 필드를 조용히 강제 변환하면 업스트림의 변경이 가려집니다.
미디어 URL은 영구 저장소가 아닙니다
릴스 동영상, 이미지, 커버, 아바타 URL은 서명되어 있거나, 변환되거나, 요청 제한이 걸리거나, 바뀔 수 있습니다. 오늘 수집한 URL이 영원히 동작하리라고 가정하지 마세요.
제품에서 미디어를 장기간 보관해야 한다면 다음을 따르세요.
- 에셋 저장이 허용되는지 확인합니다.
- 명시한 목적에 필요한 미디어만 다운로드합니다.
- 원본 URL과 수집 시각을 기록합니다.
- 보관 및 삭제 통제를 적용합니다.
- 저장한 미디어는 안전하게 제공합니다.
분석에 캡션과 지표만 필요하다면 용량이 큰 미디어 파일을 저장하는 것은 가치 없이 비용과 위험만 늘릴 수 있습니다.
릴스 성과를 신중하게 측정하기
유용한 파생 지표는 다음과 같습니다.
engagement_per_play =
(likes + comments) / plays
daily_play_growth =
(current_plays - previous_plays) / elapsed_days
입력값이 모두 있을 때만 지표를 계산하세요. 크리에이터를 비교할 때는 같은 기간과 수집 주기를 쓰세요. 두 시간 전에 게시된 릴스를 두 주 동안 관찰한 릴스와 시간 보정 없이 순위를 매겨서는 안 됩니다.
공개 수치는 감사를 거친 분석 데이터가 아니라 화면에 보이는 스냅샷입니다. 본인이 소유한 비즈니스 계정이라면 권한 기반 성과 데이터는 Instagram 공식 인사이트가 더 나은 출처입니다.
흔한 실패 사례 처리
| 사례 | 권장 처리 |
|---|---|
| 잘못된 사용자 이름 | 제출 전에 거부 |
| 비공개 계정 | 조회 불가로 표시하고 우회하지 않음 |
| 이름이 바뀐 계정 | 수동으로 확인하거나 레지스트리 갱신 |
| 공개 릴스 없음 | 빈 값의 성공 관찰로 저장 |
| 작업 타임아웃 | 다시 제출하기 전에 폴링을 재시도 |
| 지표 누락 | null 유지 |
| 중복 릴스 | ID 또는 shortcode로 Upsert |
| 만료된 미디어 URL | 사용 사례상 허용될 때만 갱신 |
빈 결과로 성공한 경우와 실패한 작업은 운영상 서로 다른 상태입니다.
책임 있는 사용
- 정당한 목적에 필요한 공개 데이터만 수집합니다.
- 비공개 프로필에 접근하거나 통제를 우회하지 않습니다.
- 민감한 개인 프로파일링을 피합니다.
- 삭제, 개인정보, 지식재산권 관련 요청을 존중합니다.
- API 키, 내보낸 파일, 미디어를 안전하게 보호합니다.
- Instagram 약관과 업체와의 계약을 검토합니다.
- 계정 작업에는 Meta의 공식 승인을 사용합니다.
SocQ는 기술적인 수집 워크플로를 제공할 뿐이며 콘텐츠에 대한 추가 권리를 부여하지 않습니다.
Instagram 릴스 API 자주 묻는 질문(FAQ)
SocQ로 릴스 URL 하나를 바로 스크래핑할 수 있나요?
현재 릴스 엔드포인트는 개별 릴스 URL이 아니라 공개 사용자 이름을 받습니다. 해당 크리에이터의 조회 가능한 공개 릴스를 반환합니다.
엔드포인트가 동영상 파일을 반환하나요?
가능한 경우 정규화된 공개 미디어 참조를 반환합니다. URL은 영구 다운로드 링크가 아니라 임시 원본 참조로 취급하세요.
조회수와 재생수는 항상 있나요?
아니요. Instagram이 지표를 숨기거나 생략할 수 있습니다. 누락된 값은 null로 보존하세요.
비공개 계정의 릴스도 수집할 수 있나요?
아니요. 공개 데이터 워크플로는 비공개 계정의 접근 통제를 우회해서는 안 됩니다.
릴스 중복은 어떻게 피하나요?
공개 릴스 ID를 우선 키로, shortcode를 대체 키로 쓰세요. 지표는 별도의 스냅샷 테이블에 저장하세요.
Meta의 공식 Instagram API를 대신 써야 하나요?
승인된 비즈니스 계정, 게시, 인사이트, 계정 작업에는 공식 API를 사용하세요. SocQ가 지원하는 공개 읽기 워크플로에는 SocQ를 사용하세요.
INSTAGRAM API
공개 Instagram URL로 워크플로를 테스트하세요
공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.
Instagram API 살펴보기