Meta Marketing API 핸드북 — 인증부터 일자별 spend·전환·크리에이티브 추출까지

#metaapi #marketingapi #graphapi #adreporting

매일 아침 광고 매니저에 들어가 날짜를 어제로 맞추고, 캠페인별로 지표를 펼치고, CSV를 내려받아 시트에 붙여넣는 일. 이 루틴을 몇 달 하다 보면 두 가지가 분명해집니다. 하나는 사람이 할 일이 아니라는 것, 다른 하나는 화면이 보여주는 숫자가 내가 원하는 분해 단위와 늘 어긋난다는 것입니다. Meta Marketing API는 이 두 문제를 동시에 풉니다. 광고 매니저가 가공해서 보여주는 숫자 대신, 광고 계정의 raw 지표를 내가 정한 분해 단위와 attribution 기준으로 직접 가져옵니다.

이 글은 마케터와 운영자가 Meta API로 데이터 파이프라인을 처음 세울 때 필요한 순서를 다룹니다. 토큰을 어떻게 발급하고, 어떤 엔드포인트로 무엇을 뽑으며, 광고 매니저 숫자와 왜 안 맞는지, 그리고 대용량 추출에서 반드시 만나는 함정까지 정리합니다.

왜 화면이 아니라 API로 가야 하나

광고 매니저 화면은 잘 만든 BI 대시보드입니다. 문제는 그 대시보드가 정한 규칙대로만 숫자를 보여준다는 데 있습니다. attribution window는 기본값으로 고정돼 있고, 분해 단위는 화면이 허용하는 조합으로 제한되며, 어제 이전 데이터를 일자별로 길게 받으려면 클릭이 늘어납니다.

API로 가면 세 가지가 풀립니다. 분해 단위를 내가 정하고, attribution window를 명시적으로 골라 받고, 다른 매체 데이터와 같은 스키마로 합쳐 한 테이블에 쌓을 수 있습니다. 마케터 입장에서 마지막 항목이 가장 큽니다. Meta, Google, TikTok을 각자의 화면에서 따로 보는 한 채널 간 ROAS 비교는 늘 사과와 오렌지를 비교하는 일이 되니까요.

📌 이 글의 전제

Graph API의 기본 개념(노드, 엣지, 필드)과 광고 계정 구조(캠페인 / 광고세트 / 광고)는 안다고 가정합니다. 코드는 파이썬 기준이지만, 핵심은 언어가 아니라 어떤 파라미터를 어떻게 조합하느냐입니다.

광고 매니저 CSV를 손으로 내려받는 대신, 토큰 한 번 발급하고 insights 엔드포인트를 매일 호출해 같은 스키마로 쌓는 구조.

토큰 발급, 여기서 대부분 막힌다

Meta API의 첫 관문은 인증이고, 처음 시도하는 사람의 절반은 여기서 하루를 씁니다. 토큰의 종류와 수명을 먼저 정리하면 길이 보입니다.

토큰 종류	수명	용도
User access token (short-lived)	약 1시간	그래프 탐색기에서 잠깐 테스트할 때
User access token (long-lived)	약 60일	사람이 주기적으로 갱신하는 임시 운영
System user token	만료 없음 (정책 변경 전까지)	자동화 파이프라인의 표준

운영 파이프라인이라면 답은 하나입니다. 비즈니스 설정에서 시스템 사용자를 만들고, 그 사용자에게 광고 계정 권한을 부여한 뒤, 시스템 사용자 토큰을 발급합니다. 사람 계정에 묶인 토큰은 비밀번호를 바꾸거나 권한 구조가 흔들리면 같이 죽지만, 시스템 사용자 토큰은 그런 사건에 영향을 덜 받습니다.

권한은 최소 ads_read가 필요하고, 캠페인을 만들거나 수정하려면 ads_management까지 받습니다. 데이터 추출만 한다면 ads_read로 충분합니다. 권한을 넓게 받아두고 싶은 유혹이 있지만, 읽기 전용 파이프라인에 관리 권한을 붙여두는 건 사고가 났을 때 피해 범위만 키웁니다.

⚠️ 앱 검수(App Review)를 빠뜨리지 말 것

내 비즈니스가 소유한 광고 계정의 데이터를 읽는 정도라면 개발 모드 앱과 시스템 사용자 토큰으로 대부분 처리됩니다. 다른 회사의 계정에 접근하거나 앱을 외부에 배포하려면 권한별 앱 검수가 필요합니다. 검수는 영업일이 걸리니, 외부 클라이언트 데이터를 다루는 컨설팅이라면 일정을 여기에 맞춰 잡아야 합니다.

insights 엔드포인트가 사실상 전부다

광고 데이터 추출의 대부분은 단 하나의 엣지에서 끝납니다. 광고 계정 노드에 붙는 /insights입니다. 캠페인 목록이나 크리에이티브 메타데이터는 다른 엔드포인트에서 가져오지만, 돈과 성과 숫자는 여기로 모입니다.

핵심 파라미터는 네 개입니다. fields는 무엇을 받을지(spend, impressions, actions 등), level은 어느 단위로 쪼갤지(account / campaign / adset / ad), time_range는 어느 기간을, time_increment는 그 기간을 며칠 단위로 나눌지를 정합니다. 마지막 파라미터가 마케터에게 특히 중요합니다. time_increment=1을 주면 기간 합계가 아니라 일자별 행으로 받습니다. 이게 빠지면 한 달치를 요청해도 한 줄로 뭉쳐 옵니다.