인스타그램 해시태그 버즈 수집: API 제약과 앱 검수 준비
인스타그램 해시태그 게시물은 공식 API로 수집할 수 있습니다. 다만 기능 승인, 비즈니스 인증, 24시간 조회 창이라는 조건이 붙습니다. 실제로 앱 검수에 반려되고 다시 준비하면서 확인한 제약과 설계 기준을 정리했습니다.
세 줄로 먼저 읽기
- 인스타그램 해시태그 검색은 Facebook Login 경로에서만 열리며 비즈니스 인증 뒤 Instagram Public Content Access 기능 승인을 받아야 합니다.
- recent_media는 조회 시점 기준 24시간 안의 공개 게시물만 돌려주고 고유 해시태그는 7일 동안 30개까지 조회할 수 있습니다.
- 이 사례의 앱 검수 반려 사유는 제출 설명과 스크린캐스트의 불일치였고 로그인부터 결과 화면까지 실제로 동작하는 영상으로 다시 준비했습니다.
인스타그램 해시태그가 달린 공개 게시물은 공식 API로 수집할 수 있습니다. API는 프로그램이 정해진 방식으로 데이터를 요청하는 통로입니다. 다만 해시태그 검색에는 조건이 여럿 붙습니다.
해시태그 검색을 쓰기까지 갖출 조건
1. 계정비즈니스나 크리에이터 계정
Facebook 페이지와 연결
2. 로그인 경로Instagram Login이 아니라
Facebook Login으로 접속
3. 비즈니스 인증기능 승인보다
먼저 마쳐야 함
4. 기능 승인앱 검수에서 Instagram
Public Content Access 통과
여기서 버즈는 브랜드가 언급된 게시물의 양을 뜻합니다. 브랜드 해시태그 버즈를 매일 쌓는 도구를 만들면서 앱 검수를 신청했다가 한 번 반려됐습니다. 이 글에는 그 과정에서 확인한 API 제약과 검수 기준, 설계에서 바꾼 부분을 담았습니다.
해시태그 검색은 Facebook Login 경로에만 있습니다
인스타그램 API는 로그인 방식에 따라 두 경로로 나뉩니다. 아래 표의 프로페셔널 계정은 비즈니스 계정이나 크리에이터 계정을 말합니다.
로그인 경로별 해시태그 검색 조건
| 항목 |  Instagram Login | Facebook Login |
|---|---|---|
| 해시태그 검색 | 제공하지 않음 | 제공 |
| 계정 요건 | 프로페셔널 계정 | 비즈니스, 크리에이터 계정 Facebook 페이지 연결 |
| 필요 기능 | – | Instagram Public Content Access |
| 기본 권한 | instagram_business_basic 계열 | instagram_basic pages_show_list pages_read_engagement |
엔드포인트는 API의 요청 주소입니다. 해시태그 게시물을 받을 때는 아래 순서로 요청을 보냅니다.
해시태그 게시물을 받는 요청 순서
1. ig_hashtag_search해시태그 문자열을
노드 ID로 바꿈
2. top_media, recent_media그 ID로 인기 게시물과
최근 게시물을 받음
3. recently_searched_hashtags지금까지 조회한
해시태그 이력을 봄
pages_show_list와 pages_read_engagement는 연결된 페이지를 찾는 단계에서도 쓰입니다. 엔드포인트마다 필요한 권한은 각 엔드포인트 문서에 따로 적혀 있습니다.
설계를 바꾸게 만든 제약 네 가지
아래 네 가지는 문서에서는 사소해 보이지만, 실제로 만들어 보면 설계를 바꾸게 되는 제약입니다. 수치로 정해진 것부터 보겠습니다.
해시태그 조회에 걸린 수치 제한
24시간recent_media 조회 창조회 시점 기준 이전 24시간
30개고유 해시태그첫 조회부터 7일 동안
recent_media는 조회한 시점에서 24시간 안에 올라온 게시물만 돌려줍니다. 10월 4일 14시에 조회하면 3일 14시 이후 게시물이 대상이고, 3일 13시에 올라온 게시물은 이미 창 밖이라 이 조회로는 받을 수 없습니다.
고유 해시태그 30개 제한은 월요일마다 초기화되는 주간 한도가 아닙니다. 해시태그마다 처음 조회한 때부터 7일 동안 개수에 들어갑니다. 그 기간에 같은 해시태그를 다시 조회해도 7일 타이머는 처음 조회한 때 그대로이고, 해시태그 ID를 저장해 둔 뒤 top_media나 recent_media만 불러도 조회 한 번으로 계산됩니다. 키워드를 넓게 벌려 탐색하는 분석에는 30개가 금방 찹니다.
응답에 들어오지 않는 게시물과 정보도 있습니다.
recent_media 응답에 들어오는 것
| 대상 |  응답에 포함 |
|---|---|
| 공개 게시물 | 제공 |
| 스토리 | 제공하지 않음 |
| 비공개 계정 게시물 | 제공하지 않음 |
| 홍보, 광고 미디어 | 제공하지 않음 |
| 작성자 username | 제공하지 않음 |
설계에 가장 크게 영향을 준 제약은 24시간 창입니다. 처음에는 하루 한 번 스캔으로 설계했다가 세 번으로 바꿨습니다. 스캔이 한 번 실패해도 다음 스캔 시점에 24시간 창 안에 남은 게시물은 다시 받을 수 있고, 창 밖으로 지난 게시물만 놓칩니다. 같은 해시태그를 7일 안에 여러 번 조회해도 고유 해시태그 수는 늘지 않지만, API 호출 사용량은 그만큼 늘어납니다.
이 사례에서는 top_media를 limit=50으로 호출하자 아래 오류가 났습니다.
Please reduce the amount of data you're asking for, then retry your request
공식 recent_media 문서는 한 페이지에 최대 50개 결과를 안내하지만, 이 사례의 top_media는 25로 낮추자 정상 응답했습니다. 같은 오류가 나면 limit 값을 낮춰 다시 요청합니다.
검수 반려 사유는 사용 사례가 아니라 스크린캐스트였습니다
스크린캐스트는 실제 앱 사용 과정을 녹화한 영상입니다. 이 사례의 앱 검수에서는 요청한 네 항목이 모두 거부됐습니다.
네 항목의 거부 사유는 같았습니다. 개발자 정책 1.6, 제품 품질 관리 조항입니다.
피드백 첫 문장에 "앱의 사용 사례는 허용되지만"이라고 적혀 있습니다. 검수자가 문제 삼은 것은 제출한 용도가 아니라, 그 용도를 보여 주는 영상이 설명과 맞지 않는다는 점이었습니다. 검수자는 세 가지를 영상에 넣으라고 요구했습니다. 전체 로그인 플로, 앱에 권한을 부여하는 사용자, 요청한 권한이 실제로 쓰이는 엔드투엔드 과정입니다. 엔드투엔드는 로그인 시작부터 결과 확인까지 끊기지 않고 이어지는 과정을 뜻합니다.
제출 서류를 다시 읽어 보니 서로 어긋나는 답이 있었습니다.
제출 내용끼리 어긋난 지점
| 확인 항목 |  리뷰어 지침공개 소비자 로그인 없음 |  통합 여부 답변Facebook 로그인 예 |  제출 영상설명용 데모 페이지 |
|---|---|---|---|
| 로그인 화면이 있다 | 제공하지 않음 | 제공 | 제공하지 않음 |
이 불일치를 거부의 직접 원인으로 판단했습니다. pages_show_list를 비롯한 세 항목의 피드백에는 요구가 하나 더 붙어 있었습니다. 서버 간 앱이거나 시스템 사용자 토큰을 쓴다면 프론트엔드 로그인 플로가 없다는 사실을 다음 제출에 적으라는 내용입니다. 앱의 실제 인증 구조를 영상과 제출 설명에 똑같이 맞추라는 요구입니다.
연결한 페이지가 목록에 보이지 않을 때
앱을 만들고 로그인까지 붙였는데, 인스타그램이 연결된 페이지가 목록에 나오지 않았습니다. 전체 작업 가운데 이 문제의 원인을 찾는 데 가장 오래 걸렸습니다.
먼저 로그인 방식과 페이지 접근 권한을 확인했습니다. 같은 계정에서 두 API가 돌려준 자산 수가 달랐습니다.
같은 계정에서 API별로 보인 자산 수
빠진 페이지를 목록에 나오게 하려고 당시에는 Facebook 로그인 for Business 구성을 검토했습니다. 구성은 앱이 요청할 자산과 권한, 토큰 종류를 묶은 설정이고, 앱 대시보드에서 만든 구성 ID를 config_id로 넘깁니다. 이 설정을 바꾸기 전에 페이지의 실제 접근 권한, 연결된 Instagram 계정, 로그인할 때 선택한 자산을 먼저 확인합니다.
액세스 토큰은 API 요청 권한을 증명하는 비밀값입니다. 이 사례에서는 사용자 로그인 과정을 영상에 보여 주려고 사용자 액세스 토큰을 골랐습니다. 토큰 종류는 검수 통과를 기준으로 고르지 말고 실제 앱의 동작과 엔드포인트 지원 조건에 맞춥니다.
config_id를 쓰면 scope 대신 구성에 정의한 권한이 적용됩니다. 아래는 당시 응답 형식을 code로 지정해 쓴 로그인 주소 예시입니다. override_default_response_type은 지정한 응답 형식으로 기본값을 덮어쓰는 옵션으로, 이 사례의 구성에서 쓴 값입니다. 중괄호 값과 API 버전은 자기 앱의 값으로 바꿔 씁니다.
https://www.facebook.com/v25.0/dialog/oauth
?client_id={app-id}
&config_id={config-id}
&redirect_uri={redirect-uri}
&state={state}
&response_type=code
&override_default_response_type=true다음으로 승인할 때 선택한 자산을 확인했습니다. 당시 비즈니스 통합 화면에는 권한 토글만 있고 페이지를 고르는 항목은 없었습니다.
권한 세 개는 모두 켜져 있는데 어느 페이지에 접근할지 고르는 항목이 없어서, 재승인 과정을 검토했습니다. 운영 중인 연결을 바로 지우면 기존 자동화가 멈추므로 테스트 환경에서 고를 수 있는 자산과 재승인 절차부터 확인했습니다. auth_type=rerequest는 거부된 권한을 다시 요청하는 플래그라서 자산 선택 화면은 다시 열리지 않습니다.
새 페이지 환경에서는 다른 현상도 나타났습니다. 페이지에 인스타그램 계정을 연결한 직후, 그 페이지가 /me/accounts 목록에서 오히려 사라졌습니다. 페이지 ID로 직접 조회하면 인스타그램 계정 정보와 페이지 액세스 토큰까지 정상으로 돌아왔기 때문에, 권한 문제가 아니라 목록에만 빠진 것으로 판단했습니다. 그래서 접근 권한이 있는 페이지 ID를 따로 조회해 목록에 합쳤습니다. 접근 권한이 없는 페이지는 ID를 알아도 이렇게 조회되지 않습니다.
수집부터 집계까지의 처리 순서
앞의 제약을 반영해 아래 순서로 수집하고 집계했습니다.
버즈 수집 스크립트의 처리 순서
1. 하루 3회 스캔한 번 실패해도
24시간 창 안에서 다시 받음- 2. 두 종류 조회recent_media와 top_media를 받고
어느 조회에서 왔는지 기록 
3. 다음 페이지까지요청당 25개씩 받고
끝까지 넘겼는지 기록
4. 중복 제거미디어 ID로 합쳐
같은 게시물은 한 건- 5. 발행일로 집계스캔 시각이 아니라
게시물이 올라온 날로 묶음
2번의 top_media는 인기 게시물을 돌려주므로 recent_media의 누락분을 채워 주지 않습니다. 3번의 25개는 한 페이지에 받는 수이고, 응답에 다음 페이지가 있으면 이어서 조회해야 합니다. 첫 25개만 받고 멈추면 수집량이 줄어듭니다. 결과가 발행 시각 순으로 온다는 보장이 없으므로 집계 전에 날짜로 정렬합니다.
4번이 필요한 이유는 같은 게시물이 여러 스캔에 잡히기 때문입니다. 밤 11시에 올라온 게시물은 다음 날 아침과 오후 스캔에 모두 들어오므로, 미디어 ID로 합치지 않으면 한 게시물이 두 건으로 집계됩니다. 스캔이 오류로 끝났다면 0건으로 넣지 말고 실패로 따로 기록합니다.
5번에서 발행일 대신 스캔 시각으로 집계하면 하루 3회 스캔이 그대로 세 구간으로 찍혀 버즈 추이가 실제와 달라집니다.
토큰과 로그인 코드는 비밀값 저장소에서 관리하고 소스 코드, 검수 영상, 공유 로그에 넣지 않습니다. 발급 후 50일 같은 고정 경고만 두지 말고 토큰의 만료와 철회를 함께 감시합니다.
위 화면은 당시 수집한 25건의 누적 결과이며, 해당 브랜드의 전체 언급량이 아니라 공개 게시물 가운데 API로 받은 양입니다. 좋아요와 댓글도 수집한 시점의 값이고, API가 주지 않은 값은 0이 아니라 빈 값으로 둡니다.
실제로 돌려 보니 브랜드 해시태그의 recent_media가 0건인 날이 있었습니다. 누적 게시물이 수백 건인 해시태그인데도 그랬습니다. 누적 게시물 수와 최근 24시간에 올라오는 양은 서로 다른 값이기 때문입니다. 오프라인 매장이나 전시처럼 방문이 특정 요일에 몰리는 브랜드라면 평일에는 조회 결과가 비는 날이 잦습니다.
승인 전 테스트와 운영을 구분하기
당시 앱 역할을 가진 계정에서는 승인 전에도 해시태그 ID 조회와 게시물 수집이 동작했습니다. 일반 액세스 레벨 문서는 앱 역할 보유자에게 적용되는 Standard Access와 외부 앱 사용자에게 필요한 Advanced Access를 나눠 설명합니다. 그런데 Instagram Public Content Access 기능은 라이브 데이터에 접근하기 전에 앱 검수와 비즈니스 인증을 따로 요구합니다.
테스트에서 운영까지 거치는 상태
1. 테스트 성공앱 역할 계정에서
승인 전 수집 동작- 2. 비즈니스 인증기능 승인 전에
먼저 마침 - 3. 기능 승인앱 검수에서
권한과 기능별로 통과 
4. 라이브 모드외부 사용자 계정의
데이터를 수집
승인을 받아도 24시간 조회 창과 해시태그 30개 제한은 그대로입니다. 승인으로 달라지는 것은 앱을 쓸 수 있는 사용자와 기능의 범위입니다. 호출 가능한 양은 API와 토큰마다 다르므로, 앱 대시보드의 사용량 표시와 응답 헤더에서 확인합니다.
재제출을 준비하며 바꾼 것
검수 피드백에 맞춰 네 가지를 다시 만들었습니다.
재제출 전에 바꾼 네 가지
1. 실제 동작 화면데모 페이지 대신
로그인부터 결과까지 이어지는 웹앱- 2. 화면에 권한 표시각 화면 옆에
그 화면이 쓰는 권한 이름을 적음 
3. 빈 결과 안내0건이면 24시간 창 사양이라고
화면에 띄움- 4. 자동 녹화로그인만 사람이 하고
나머지는 스크립트로 녹화
2번은 페이지 목록 옆에 pages_show_list, 인스타그램 계정 카드 옆에 pages_read_engagement와 instagram_basic을 적는 방식입니다. 검수자가 영상만 보고도 어느 화면에서 어느 권한을 쓰는지 짝지을 수 있습니다.
3번은 recent_media가 0건일 때 빈 화면을 그대로 두면 오류로 보이기 때문에 넣었습니다. 안내 문구를 띄운 뒤, 게시물이 많은 연관 해시태그로 같은 엔드포인트가 데이터를 돌려주는 장면을 이어 붙였습니다.
4번은 로그인 뒤의 조작을 스크립트가 일정한 속도로 진행하고 구간마다 영어 자막을 얹는 방식입니다. 손으로 녹화할 때보다 다시 찍는 부담이 훨씬 적습니다.
자주 묻는 질문
Instagram Login 경로로도 해시태그를 검색할 수 있나요?
검색할 수 없습니다. 해시태그 검색 엔드포인트는 Facebook Login 경로에만 열려 있어서 Instagram Login 쪽에 권한을 아무리 붙여도 호출되지 않습니다. 프로페셔널 계정과 Facebook 페이지 연결, Instagram Public Content Access 기능 승인이 함께 필요합니다.
기능 승인을 받으면 데이터를 더 많이 가져올 수 있나요?
승인을 받아도 24시간 조회 창과 고유 해시태그 30개 제한은 그대로입니다. 승인으로 달라지는 것은 앱을 쓸 수 있는 사용자와 기능의 범위이고, 호출 가능한 양은 API와 앱의 사용량 정보에서 따로 봅니다.
recent_media가 0건으로 나오면 수집이 잘못된 건가요?
정상 응답일 수 있습니다. 0건은 최근 24시간에 받은 공개 게시물이 없다는 뜻이며, 그보다 앞선 게시물과 비공개 게시물은 이 값에 들어가지 않습니다. 수집 쪽에서는 응답에 오류 객체가 없는지, 요청한 해시태그 ID가 맞는지, 다음 페이지가 남았는지 점검합니다. 호출 횟수를 늘리기 전에 권한 오류와 정상적인 빈 응답부터 구분합니다.
참고 자료
- Hashtag Search, Instagram Platform
- IG Hashtag Recent Media 엣지 레퍼런스
- Instagram Public Content Access 기능 문서
- Access Levels, App Development with Meta
- Facebook Login for Business
3줄 요약
-
인스타그램 해시태그 검색은 Facebook Login 경로에서만 열리며 비즈니스 인증 뒤 Instagram Public Content Access 기능 승인을 받아야 합니다.
-
recent_media는 조회 시점 기준 24시간 안의 공개 게시물만 돌려주고 고유 해시태그는 7일 동안 30개까지 조회할 수 있습니다.
-
이 사례의 앱 검수 반려 사유는 제출 설명과 스크린캐스트의 불일치였고 로그인부터 결과 화면까지 실제로 동작하는 영상으로 다시 준비했습니다.
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
브랜드 해시태그 버즈를 매일 수집하려는 상황에서, 수집 스크립트를 하루 한 번만 돌리는 설계는 어떻게 보시나요?
새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.
이 글이 도움이 되었나요?
메일, 회의록, 리포트처럼 반복되는 일을 AI로 자동화하는 순서와 안전장치를 다룹니다
코스 전체 보기 →