instagram/
highlight-items

알고 있는 Instagram 하이라이트 ID에서 공개 스토리 항목을 조회하여, 텍스트, 작성자 정보, 공개된 지표, 미디어 상세 정보, 출처 정보를 담은 정규화된 레코드로 반환합니다.

Instagram Highlight Items API

알고 있는 하이라이트 ID
스토리 항목 레코드
미디어와 출처 정보
결과당 0.5 크레딧
준비됨
준비됨

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

README

SocQ 작성 · 업데이트

Instagram Highlight Items

Instagram 하이라이트 항목은 공개 프로필의 하이라이트 안에 저장된 스토리로, 텍스트, 작성자 정보, 미디어 참조 정보, 타임스탬프, 공개된 참여 신호를 담고 있습니다. 이러한 레코드는 하이라이트 콘텐츠 목록 작성, 미디어 검토, 출처를 고려한 리포팅, 알고 있는 하이라이트 간 비교에 활용할 수 있습니다.

Instagram Highlight Items API 주요 기능

  • 여러 하이라이트 입력숫자형 하이라이트 ID를 하나 이상 제출하면, 제공한 식별자마다 상위 조회가 한 번씩 수행됩니다.
  • 정규화된 스토리 항목 레코드항목 ID, 공개 URL, 제목 또는 캡션 텍스트, 작성자 정보, 공개된 지표, 미디어 메타데이터, 타임스탬프를 하나의 레코드 구조로 받습니다.
  • 출처 하이라이트 표기반환된 항목마다 제출한 하이라이트 ID를 extra.highlight_id에 유지하므로, 여러 하이라이트의 레코드도 구분할 수 있습니다.

Instagram Highlight Items API 매개변수

매개변수필수설명
highlight_ids필수알고 있는 Instagram 하이라이트 ID를 비어 있지 않은 숫자 문자열로, 쉼표나 줄바꿈으로 구분해 하나 이상 지정합니다.

Instagram Highlight Items API 사용 방법

알고 있는 하이라이트 ID를 비동기 작업으로 제출하고, 작업 ID를 폴링한 뒤, 저장된 정규화 레코드를 결과 커서 페이지네이션으로 읽습니다.

  1. 유효한 숫자형 하이라이트 ID를 하나 이상 준비합니다. ID를 모르면 먼저 사용자 이름으로 Story Highlights를 수집하고, 반환된 컨테이너 레코드에서 extra.highlight_id를 읽습니다.
  2. highlight_ids를 /v1/instagram/highlight-items로 POST합니다.
  3. status가 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. /v1/tasks/{task_id}?limit=50을 읽고, results.has_more가 true인 동안 results.next_cursor를 따라갑니다.
# Replace the documented sample with a current highlight ID before running.
curl -X POST "https://api.socq.ai/v1/instagram/highlight-items" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"highlight_ids":["18067016518767507"]}'

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

Instagram Highlight Items API 추천 활용 사례

  • 저장된 스토리 콘텐츠 목록 작성: 반환된 항목 ID, 텍스트, 공개 URL, 미디어 참조 정보, 타임스탬프를 알고 있는 하이라이트별로 검토 가능한 목록으로 정리합니다.
  • 하이라이트 미디어 검토: 각 하이라이트에서 현재 노출되는 스토리 항목의 이미지·동영상 URL, 썸네일, 크기, 재생 시간, 캡션, 작성자 정보를 살펴봅니다.
  • 하이라이트 간 비교: extra.highlight_id별로 레코드를 묶어, 선택한 하이라이트 간에 반환된 콘텐츠 유형, 게시 시각, 작성자, 공개된 지표를 비교합니다.

Instagram Highlight Items API 활용 팁

  • 하이라이트 ID를 모르면 먼저 사용자 이름으로 instagram/story-highlights를 호출하고, 성공한 결과의 extra.highlight_id를 사용하세요. 이 엔드포인트는 사용자 이름에서 ID를 찾아 주지 않습니다.
  • 수집기는 제공한 값마다 독립적으로 조회하므로, 제출하기 전에 중복된 ID를 제거하세요.
  • results_limit은 추가하지 마세요. 하이라이트 ID마다 한 번의 상위 응답에 있는 항목이 반환됩니다.
  • 두 레코드 계열 모두 type이 story이므로, highlight-items와 story-highlights는 resource로 구분하세요.
  • 텍스트, 작성자 필드, 지표, 미디어, URL, 타임스탬프는 선택 값으로 취급하고, 사용할 수 없거나 삭제된 스토리 항목은 레코드가 생성되지 않을 수 있다고 전제하세요.
  • results.next_cursor는 저장된 작업 레코드를 추가로 읽을 때만 따라가세요. Instagram에서 수집을 이어 가는 값이 아닙니다.

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

  • Instagram Posts API — 사용자 이름으로 공개 게시물, 미디어, 해시태그, 멘션, 타임스탬프, 참여도를 수집합니다.
  • Instagram Reels API — 사용자 이름으로 공개 릴스, 미디어, 오디오, 해시태그, 멘션, 참여도를 수집합니다.
  • Instagram Profiles API — 사용자 이름으로 공개 프로필 정보, 소개글, 링크, 계정 속성, 카테고리, 공개된 수치를 가져옵니다.
  • Instagram Tagged Posts API — 선택한 프로필을 태그한 공개 게시물을 수집하며, 작성자, 미디어, 멘션, 태그된 사용자 맥락, 참여도를 포함합니다.
  • Instagram Transcript API — 공개 게시물 또는 릴스 URL에서 스크립트 텍스트, 언어, 형식, 출처 URL, 숏코드를 추출합니다.
  • Instagram Story Highlights API — 사용자 이름으로 공개 스토리 하이라이트 목록을 조회하며, 제목, 소유자 맥락, 미디어 수, 재사용 가능한 하이라이트 ID를 포함합니다.

다른 플랫폼 둘러보기

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

Instagram Highlight Items API — 자주 묻는 질문

Instagram Highlight Items API는 알고 있는 숫자형 Instagram 하이라이트 ID에서 공개 스토리 항목을 가져오는 프로그래밍 인터페이스입니다. 정규화된 항목 식별 정보, 텍스트, 작성자, 공개된 지표, 미디어 메타데이터, 타임스탬프, 출처 하이라이트 정보를 반환합니다.

알고 있는 유효한 하이라이트 ID를 사용하거나, 먼저 사용자 이름으로 Story Highlights를 수집하세요. instagram/story-highlights 결과가 성공하면 출처 식별자를 extra.highlight_id로 제공합니다(제공되는 경우). 이 엔드포인트는 사용자 이름을 받지 않습니다.

정규화된 항목에는 ID, URL, 텍스트, 작성자 ID, 사용자 이름과 이름, 공개된 지표, 이미지 또는 동영상 메타데이터, created_at, collected_at, extra.highlight_id가 포함될 수 있습니다. 필드의 제공 여부는 공개 상위 응답을 따릅니다.

results_limit은 받지 않으며, 수집기는 하이라이트 ID마다 상위 요청을 한 번 보냅니다. 다만 작업 결과 엔드포인트에서는 limit과 results.next_cursor로 저장된 레코드를 페이지네이션할 수 있습니다.

하이라이트에 현재 노출되는 레코드가 없거나, 스토리 항목이 삭제되었거나, 제한되었거나, 비공개로 전환되었거나, 이용할 수 없게 되었을 수 있습니다. 작업은 현재 공개 응답에 있는 레코드만 저장합니다.

반환된 정규화 레코드 1건당 0.5 크레딧이 청구되며 기본 요금은 없습니다. 예상 요금은 제출한 하이라이트 ID당 레코드 20건을 기준으로 하고, 최종 사용량은 실제로 반환된 레코드를 따릅니다.