인스타그램 해시태그 API 수집 조건과 메타 앱 검수 통과 기준

인스타그램 해시태그가 달린 공개 게시물은 공식 API로 수집할 수 있습니다. 다만 조건이 여럿 붙습니다. Facebook 로그인 경로를 써야 하고, Instagram Public Content Access 기능 승인을 받아야 하며, 그 승인에는 비즈니스 인증이 선행되어야 합니다.

브랜드 해시태그 버즈를 매일 누적하는 도구를 만들면서 앱 검수에 한 차례 반려됐습니다. 그 과정에서 확인한 API 제약과 검수 기준, 그리고 설계에서 바꿔야 했던 부분을 정리했습니다.

해시태그 검색이 가능한 경로는 하나뿐입니다

인스타그램 API는 로그인 방식에 따라 두 가지로 나뉩니다. 해시태그 검색은 그중 한쪽에만 있습니다.

항목	Instagram Login	Facebook Login
해시태그 검색	미지원	지원
계정 요건	인스타그램 프로페셔널 계정	프로페셔널 계정 + Facebook 페이지 연결
필요 기능	해당 없음	Instagram Public Content Access
기본 권한	instagram_business_basic 계열	instagram_basic, pages_show_list, pages_read_engagement

Instagram Login 경로로 아무리 권한을 붙여도 해시태그 검색 엔드포인트는 열리지 않습니다. 반드시 Facebook Login 경로를 써야 합니다.

엔드포인트는 네 개입니다. ig_hashtag_search로 해시태그 문자열을 노드 ID로 바꾸고, 그 ID에 top_media나 recent_media를 붙여 게시물을 받습니다. 검색 이력은 recently_searched_hashtags로 확인합니다.

실무에서 걸리는 제약 네 가지

문서를 읽을 때는 사소해 보이지만 설계를 바꾸게 만드는 제약들입니다.

제약	내용	설계에 미치는 영향
24시간 창	recent_media는 쿼리 시점 기준 24시간 이내 게시물만 반환	소급 조회 불가. 스캔 실패가 곧 데이터 손실
작성자 미상	반환 필드에 username 없음	인플루언서 발굴이나 UGC 리포스트 요청 불가
해시태그 30개	7일 롤링 기준 고유 해시태그 30개	키워드를 넓게 벌리는 탐색적 분석이 어려움
공개 게시물만	스토리 미포함, 비공개 계정 제외	방문 인증 스토리 비중이 큰 업종은 커버리지 손실

가장 크게 작용한 것은 24시간 창입니다. 하루 한 번 스캔으로 설계했다가 세 번으로 바꿨습니다. 서버가 잠깐 멈추거나 토큰이 만료된 날의 게시물은 어떤 방법으로도 되찾을 수 없습니다. 같은 해시태그를 여러 번 호출해도 30개 한도에는 하나로만 계산되니 반복 호출에 드는 부담이 적습니다.

문서에 없는 제약도 하나 있었습니다. top_media를 limit=50으로 호출하면 데이터량 초과 오류가 납니다.

Please reduce the amount of data you're asking for, then retry your request

25로 낮추면 정상 응답합니다. 미디어 URL을 포함한 필드 조합에서 응답 크기가 한도를 넘긴 것으로 보입니다.

검수 반려 사유는 사용 사례가 아니라 스크린캐스트였습니다

앱 검수에서 요청한 네 항목이 모두 거부됐습니다.

앱 검수 결과 화면. Instagram Public Content Access, pages_show_list, pages_read_engagement, instagram_basic이 Not approved로 표시되고 public_profile만 Approved 배지가 붙어 있다

거부 사유는 네 항목 모두 동일했습니다. 개발자 정책 1.6, 제품 품질 관리 조항입니다.

검수 피드백 상세. 사용 사례 상세 정보와 일치하지 않는 스크린캐스트라는 제목 아래 전체 로그인 플로, 권한을 부여하는 사용자, 사용 사례의 엔드투엔드 경험을 포함하라는 요구가 번호로 나열되어 있다

피드백 첫 문장이 중요합니다. "앱의 사용 사례는 허용되지만"이라고 명시되어 있습니다. 브랜드 해시태그 모니터링이라는 용도 자체는 통과했고, 문제는 증빙 영상이었습니다. 사용 사례 문구를 다시 쓸 필요가 없다는 뜻이라 오히려 다행인 반려였습니다.

검수자가 요구한 것은 세 가지입니다. 전체 로그인 플로, 앱에 권한을 부여하는 사용자, 요청한 권한이 실제로 쓰이는 엔드투엔드 경험입니다.

제출 서류를 다시 읽어 보니 모순이 있었습니다. 리뷰어 지침에 "공개 소비자 로그인이 없다"라고 적어 놓고 Facebook 로그인 통합 여부에는 "예"라고 답한 상태였습니다. 검수자는 로그인 화면을 기대했는데 영상에는 설명용 데모 페이지만 있었습니다. 이 불일치가 거부의 직접 원인으로 보입니다.

pages_show_list를 비롯한 세 항목의 피드백에는 항목이 하나 더 붙어 있었습니다. 서버 간 앱이거나 시스템 사용자 토큰을 쓴다면 프론트엔드 로그인 플로가 없다는 사실을 다음 제출에 명시하라는 내용입니다. 검수자가 탈출구를 알려준 셈인데, 지금 제출은 두 길 사이에 어정쩡하게 걸쳐 있었습니다.

페이지가 목록에 보이지 않는 문제

앱을 만들어 로그인까지 붙였는데 정작 인스타그램이 연결된 페이지가 목록에 나오지 않았습니다. 원인을 찾는 데 가장 오래 걸린 구간입니다.

첫 번째 원인은 로그인 방식이었습니다. 일반 Facebook 로그인으로 받은 토큰의 /me/accounts는 사용자가 직접 페이지 역할을 가진 페이지만 반환합니다. 비즈니스 포트폴리오가 소유한 페이지는 여기에 나오지 않습니다. 같은 계정을 광고 API로 조회하면 19개가 잡히는데 /me/accounts로는 6개만 나오는 상황이 그래서 생깁니다.

해결하려면 Facebook 로그인 for Business 구성을 만들어야 합니다. 앱 대시보드에서 구성을 만들고 발급된 구성 ID를 로그인 URL에 config_id로 붙이는 방식입니다.

Facebook 로그인 for Business 구성 만들기 화면. 액세스 토큰 선택 단계에서 사용자 액세스 토큰과 시스템 사용자 액세스 토큰 두 가지가 라디오 버튼으로 제시되어 있다

액세스 토큰 유형은 검수를 앞둔 상황이라면 사용자 액세스 토큰이 낫습니다. 시스템 사용자 토큰은 만료가 없어 운영에는 유리하지만, 프론트엔드 로그인 플로가 없다는 점을 검수자에게 따로 설명해야 합니다. 반려 사유가 로그인 플로 부재였던 상황에서 같은 위험을 다시 안을 이유가 없습니다.

config_id를 쓸 때는 scope 대신 구성에 정의된 권한이 적용됩니다. 코드 흐름을 그대로 유지하려면 override_default_response_type을 함께 넘겨야 합니다.

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

두 번째 원인은 페이지 권한 목록이 로그인 시점에 고정된다는 점입니다. 앱이 접근할 페이지는 최초 승인 때 정해지고, 이후 비즈니스 통합 설정에서는 권한 토글만 바꿀 수 있습니다.

비즈니스 통합 설정의 앱 상세 화면. Instagram 계정의 프로필 및 게시물 액세스, 페이지에 게시된 콘텐츠 읽기, 관리 중인 페이지 리스트를 표시 세 항목이 켜져 있고 페이지를 고르는 항목은 보이지 않는다

권한 세 개는 모두 켜져 있는데 어떤 페이지에 접근할지 고르는 항목이 없습니다. 페이지 목록을 바꾸려면 연결을 삭제하고 다시 승인해야 합니다. auth_type=rerequest는 거부된 권한을 재요청하는 플래그일 뿐 자산 선택 화면을 다시 열지 않습니다.

세 번째 원인은 새 페이지 환경이었습니다. 페이지에 인스타그램 계정을 연결한 직후, 그 페이지가 /me/accounts 목록에서 오히려 사라졌습니다. 페이지 ID로 직접 조회하면 인스타그램 계정 정보와 페이지 액세스 토큰까지 정상적으로 반환되는데 목록에만 없었습니다. 권한 문제가 아니라 목록 반환 조건의 문제입니다. 알려진 페이지 ID를 따로 조회해 목록에 병합하는 방식으로 우회했습니다.

수집 파이프라인 설계

제약을 반영해 정리한 구조입니다.

항목	설계	이유
스캔 주기	하루 3회	24시간 창에서 한 번 실패해도 복구 여지를 남김
조회 엣지	recent_media와 top_media 모두	recent가 비는 날을 top이 일부 메움
중복 제거	미디어 ID를 키로 병합	같은 게시물을 여러 번 받아도 한 건으로 집계
집계 기준	게시물 발행 시각	스캔 시각 기준으로 잡으면 실제 버즈 시점이 뭉개짐
호출 한도	limit 25	50은 데이터량 초과 오류
토큰	장기 토큰 파일 저장, 50일 경과 시 경고	브라우저 없이 스케줄 실행

집계 기준을 발행 시각으로 잡은 점이 중요합니다. 스캔 시각으로 세면 하루 3회 스캔이 그대로 3개 구간으로 찍혀 버즈 추이가 왜곡됩니다.

완성된 대시보드의 누적 버즈 화면. 게시물 25건, 좋아요 993, 댓글 49, 활동일 24일 지표와 발행일 기준 일자별 막대 차트, 최근 스캔 이력이 표시되어 있다

실제로 돌려 보니 브랜드 해시태그의 recent_media가 0건으로 나오는 날이 있었습니다. 누적 게시물이 수백 건인 해시태그인데도 그렇습니다. 누적치와 24시간 창에 들어오는 양은 별개이기 때문입니다. 오프라인 매장이나 전시처럼 방문이 특정 요일에 몰리는 경우, 평일 조회는 자주 빕니다.

승인 전에도 수집이 되는 이유

기능 승인을 받기 전인데도 ig_hashtag_search 호출이 통과했습니다. 표준 액세스 때문입니다. 앱을 만들면 자동으로 부여되며, 앱에 역할이 있는 사용자의 계정으로는 승인되지 않은 엔드포인트도 호출됩니다. 앱 관리자 계정 하나로 돌리는 내부 도구라면 조건을 충족합니다.

실제로 이 상태에서 해시태그 노드 조회, 인기 게시물 25건 수집, 24시간 이내 게시물 조회, 중복 제거 누적까지 전부 정상 작동했습니다. 하루 세 번 스캔을 돌리는 데도 문제가 없습니다.

기능 승인을 받으면 달라지는 것과 그대로인 것

여기서 오해하기 쉬운 부분이 있습니다. 승인을 받으면 더 많이, 더 자주 가져올 수 있다고 생각하기 쉽지만 그렇지 않습니다.

항목	표준 액세스	기능 승인 후
해시태그 조회 자체	앱 역할 보유자 계정으로 가능	동일
반환되는 데이터	공개 게시물 전체	동일
고유 해시태그 30개 / 7일	적용	그대로 적용
24시간 창	적용	그대로 적용
시간당 호출 한도	200 곱하기 앱 사용자 수	같은 공식
앱 역할이 없는 사용자	호출 불가	호출 가능
공식 문서상 용도	개발과 테스트	프로덕션 운영

Meta 문서는 플랫폼 사용 제한을 시간당 호출 수 = 200 × 사용자 수로 규정합니다. 이 공식에 액세스 등급은 들어가지 않습니다. 표준과 고급의 할당량 차이는 광고 관리 API 같은 비즈니스 사용 사례 제한에서 벌어지며, 해시태그 검색은 그 대상이 아닙니다.

해시태그 30개 제한도 인스타그램 계정 단위로 걸리는 값이라 승인 여부와 무관합니다. 즉 승인은 호출량을 늘려 주지 않습니다.

그렇다면 왜 받아야 하는지가 남습니다. 이유는 세 가지입니다.

앱 역할이 없는 사람에게도 열립니다. 담당자가 늘거나 실무자가 직접 로그인해 보려면 승인이 필요합니다. 표준 액세스에서는 쓸 사람마다 앱에 개발자나 테스터로 등록해야 하는데, 인원이 늘수록 관리가 번거로워집니다.
라이브 모드 전환이 열립니다. 개발 모드에 머무는 앱은 외부에 공개된 서비스로 보기 어렵습니다.
정책상 근거가 생깁니다. 공식 문서는 표준 액세스를 "앱에서 역할이 부여된 사용자만 사용할 앱"과 개발 중 테스트 용도로 규정합니다. 금지한다고 못 박지는 않았지만, 고객사 납품물의 데이터 출처로 삼기에는 약합니다. 연례 데이터 액세스 갱신에서도 승인된 기능이 있는 편이 안정적입니다.

정리하면 승인은 성능이 아니라 자격을 얻는 절차입니다. 데이터의 양과 종류는 지금과 같습니다.

그래서 순서를 이렇게 잡았습니다. 승인을 기다리는 동안 데이터 수집은 지금 구조로 시작하고, 기능 승인은 별도로 진행합니다. 24시간 창이 소급되지 않는다는 제약 때문에 심사 기간의 게시물을 그냥 흘려보낼 이유가 없습니다.

재제출을 준비하며 바꾼 것

검수 통과를 위해 다시 만든 항목들입니다.

실제로 동작하는 화면을 배포했습니다. 설명용 데모 페이지가 아니라 로그인부터 결과 렌더링까지 이어지는 웹 애플리케이션입니다.
각 화면에 사용 권한을 표시했습니다. 페이지 목록 옆에 pages_show_list, 인스타그램 계정 카드 옆에 pages_read_engagement와 instagram_basic을 적어 두면 검수자가 영상만 보고 대응 관계를 확인할 수 있습니다.
빈 결과를 설명으로 처리했습니다. recent_media가 0건일 때 빈 화면을 그대로 두면 오류로 읽힙니다. 24시간 창 사양이라는 안내를 화면에 띄우고, 볼륨이 큰 연관 해시태그로 같은 엔드포인트가 데이터를 반환하는 장면을 이어 붙였습니다.
스크린캐스트를 자동 녹화했습니다. 로그인만 사람이 하고 이후 조작은 스크립트가 일정한 속도로 진행하며 구간마다 영어 자막을 얹는 방식입니다. 수동 녹화보다 재촬영 부담이 훨씬 적습니다.

빈 결과를 설명으로 처리한 부분이 특히 중요합니다. 제약을 감추면 검수자에게는 버그로 보이고, 설명하면 사양을 이해하고 만든 앱으로 읽힙니다.

3줄 요약

인스타그램 해시태그 게시물 수집은 Facebook 로그인 경로와 Instagram Public Content Access 승인이 필요하며, 그 승인에는 비즈니스 인증이 선행됩니다.
recent_media는 24시간 창이고 소급 조회가 안 되므로 스캔은 하루 여러 번 돌리고, 집계는 스캔 시각이 아니라 게시물 발행 시각을 기준으로 삼아야 합니다.
앱 검수 통과 여부는 사용 사례보다 스크린캐스트에서 달라집니다. 로그인 플로와 권한 부여 화면, 결과 렌더링까지 끊지 않고 담아야 하고 제출 문서와 영상의 내용이 어긋나면 안 됩니다.