instagram/
story-highlights

사용자 이름으로 공개 Instagram 스토리 하이라이트 컨테이너를 수집하고, 제목, 소유자 정보, 미디어, 항목 수, 재사용할 수 있는 하이라이트 ID를 반환합니다.

Instagram Story Highlights API

사용자 이름으로 조회
하이라이트 컨테이너
재사용 가능한 하이라이트 ID
결과당 0.5 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

Instagram Story Highlights

Instagram 스토리 하이라이트는 공개 프로필에 저장된 스토리 모음으로, 제목별로 정리되어 소유자 정보, 커버 미디어, 항목 수를 갖추고 있습니다. 이러한 컨테이너 레코드는 프로필의 카테고리 목록 작성, 계정 간 비교, 항목 단위 검토를 위한 하이라이트 선별에 활용할 수 있습니다.

Instagram Story Highlights API 주요 기능

  • 여러 프로필의 하이라이트 목록Instagram 사용자 이름을 하나 이상 제출하면 계정별로 공개된 스토리 하이라이트 컨테이너를 소유자 정보와 함께 나열합니다.
  • 컨테이너 식별 정보와 맥락정규화된 하이라이트 ID, 제목, URL, 소유자 정보, 직접 노출된 미디어, 타임스탬프, 공개된 수치, 보고된 항목 총수를 받습니다.
  • 항목 단위 수집으로 연결extra.highlight_id로 컨테이너와의 관계를 유지하고, 숫자형 하이라이트 ID를 항목 단위 수집 워크플로에 전달합니다.

Instagram Story Highlights API 매개변수

매개변수필수설명
usernames필수비어 있지 않은 핸들 형태의 공개 Instagram 사용자 이름 하나 이상입니다. 앞의 @는 허용되며 수집 전에 제거됩니다.

Instagram Story Highlights API 사용 방법

공개 계정의 사용자 이름을 비동기 작업으로 제출하고, 작업 ID를 폴링한 뒤, 정규화된 하이라이트 컨테이너를 결과 커서 페이지네이션으로 읽습니다.

  1. 프로필 URL이 아닌 핸들 형태로 공개 Instagram 사용자 이름을 하나 이상 준비합니다.
  2. usernames를 /v1/instagram/story-highlights로 POST합니다.
  3. status가 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. data.results.items를 읽고, results.has_more가 true인 동안 results.next_cursor를 따라가며 가져옵니다.
curl -X POST "https://api.socq.ai/v1/instagram/story-highlights" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["instagram"]}'

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

Instagram Story Highlights API 추천 활용 사례

  • 공개 프로필의 카테고리 목록 작성: 하이라이트 제목, 소유자 정보, URL, 미디어 수를 정리해 프로필에 보이는 저장된 스토리 카테고리 목록을 만듭니다.
  • 계정 간 하이라이트 비교: 제출한 공개 사용자 이름들의 컨테이너 제목, 보고된 항목 총수, 미디어 참조, 확인 가능한 타임스탬프를 비교합니다.
  • 수집할 스토리 모음 선택: extra.highlight_id를 제목, media_count와 함께 활용해 이후 항목 단위 조회에 사용할 숫자형 하이라이트 컨테이너를 고릅니다.

Instagram Story Highlights API 활용 팁

  • 프로필 URL은 핸들로 변환되지 않으므로, 제출 전에 앞의 @를 제거하고 중복된 사용자 이름을 정리해 핸들을 정규화하세요.
  • 사용자 이름마다 하이라이트 목록을 한 번씩만 요청하며 results_limit나 제공처 연속 조회가 없으므로, 계정별 수집 레코드는 제공되는 컨테이너 목록에 따라 정해집니다.
  • 작업 결과의 next_cursor는 저장된 정규화 레코드를 페이지로 나누어 읽을 때만 사용하세요. Instagram에 하이라이트의 다음 페이지를 요청하는 것이 아닙니다.
  • 개별 스토리 프레임이 필요할 때는 값이 있는 숫자형 extra.highlight_id만 instagram/highlight-items에 전달하세요.
  • 결과가 비어 있으면 하이라이트가 없거나 프로필을 사용할 수 없는 경우일 수 있다고 보고, 선택 항목인 미디어·수치·URL·타임스탬프가 항상 있다고 가정하지 마세요.

Instagram Story Highlights API 외에 Instagram의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • Instagram Posts API — 사용자 이름으로 공개 게시물, 미디어, 해시태그, 멘션, 타임스탬프, 참여도를 수집합니다.
  • Instagram Reels API — 사용자 이름으로 공개 릴스, 미디어, 오디오, 해시태그, 멘션, 참여도를 수집합니다.
  • Instagram Profiles API — 사용자 이름으로 공개 프로필 정보, 소개글, 링크, 계정 속성, 카테고리, 공개된 수치를 가져옵니다.
  • Instagram Tagged Posts API — 선택한 프로필을 태그한 공개 게시물을 수집하며, 작성자, 미디어, 멘션, 태그된 사용자 맥락, 참여도를 포함합니다.
  • Instagram Highlight Items API — 알고 있는 하이라이트 ID에서 저장된 공개 스토리 항목을 가져오며, 텍스트, 작성자 정보, 미디어, 타임스탬프, 공개된 지표, 출처 맥락을 포함합니다.
  • Instagram Stories API — 사용자 이름으로 공개 계정이 현재 게시 중인 스토리를 수집하며, 스토리 미디어, 게시 시각, 만료 시각을 포함합니다.

다른 플랫폼 둘러보기

Instagram 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

Instagram Story Highlights API — 자주 묻는 질문

Instagram Story Highlights API는 제출한 Instagram 사용자 이름의 공개 스토리 하이라이트 컨테이너를 나열하는 프로그래밍 인터페이스입니다. 정규화된 컨테이너 ID, 제목, 소유자 정보, 미디어, 공개된 수치, 항목 수, 재사용 가능한 하이라이트 ID를 반환합니다.

Instagram 계정 핸들로 이루어진, 비어 있지 않은 배열을 제출합니다. 앞의 @는 제거되지만 프로필 URL은 사용자 이름으로 변환되지 않으므로, 보내기 전에 핸들을 정규화하고 중복을 제거하세요.

아니요. 하이라이트 컨테이너만 반환합니다. 컨테이너 안의 개별 스토리 항목이 필요하면 값이 있는 숫자형 extra.highlight_id를 instagram/highlight-items와 함께 사용하세요.

레코드에는 컨테이너 ID, URL, 제목, 소유자 ID, 사용자 이름과 이름, 직접 노출된 미디어, 일반적인 공개 수치, created_at, collected_at, extra.highlight_id, extra.media_count가 포함될 수 있습니다.

호출자가 제어하는 results_limit나 제공처 연속 조회는 구현되어 있지 않습니다. 사용자 이름마다 한 번씩만 요청하며, 작업 엔드포인트의 cursor와 limit는 이미 저장된 정규화 레코드를 페이지로 나누는 용도로만 쓰입니다.

공개 프로필에 저장된 하이라이트가 없거나, 계정이 비공개이거나 사용할 수 없거나 제한된 상태일 수 있습니다. items 배열이 비어 있는 succeeded 작업은 결과 없음이라는 정상적인 결과로 처리하세요.

저장된 정규화 하이라이트 1건당 0.5 크레딧이 차감되며, 기본 요금은 없습니다. 예상 금액은 제출한 사용자 이름마다 결과 20건을 기준으로 계산하고, 최종 사용량은 실제로 저장된 레코드 수에 따라 정해집니다.