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

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

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

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

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

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

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

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

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

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

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

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

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

import requests

ACCOUNT_ID = "act_1234567890"
TOKEN = "<system_user_token>"

params = {
    "fields": "campaign_name,spend,impressions,actions,action_values",
    "level": "campaign",
    "time_range": '{"since":"2026-06-01","until":"2026-06-07"}',
    "time_increment": 1,           # 일자별로 쪼개기
    "action_attribution_windows": '["7d_click","1d_view"]',
    "access_token": TOKEN,
}
r = requests.get(
    f"https://graph.facebook.com/v20.0/{ACCOUNT_ID}/insights",
    params=params,
)
rows = r.json()["data"]   # 캠페인 x 날짜 단위 행 목록

여기서 actions와 action_values가 전환 데이터입니다. actions는 전환 건수, action_values는 전환 매출입니다. 둘 다 단일 숫자가 아니라 전환 유형별 배열로 옵니다. 구매, 장바구니 추가, 리드가 한 배열에 섞여 있어서, 내가 원하는 전환 유형(보통 purchase 또는 offsite_conversion.fb_pixel_purchase)을 코드에서 골라내야 합니다. 이 구조를 모르고 actions를 통째로 숫자로 취급하면 파이프라인이 첫날부터 깨집니다.

광고 매니저 숫자와 안 맞는 이유, attribution window

API로 뽑은 전환 수가 광고 매니저 화면과 다르다는 질문은 거의 매일 나옵니다. 원인의 대부분은 attribution window입니다.

attribution window는 “광고를 보거나 클릭한 뒤 며칠 안에 일어난 전환까지 이 광고 덕으로 칠 것인가”를 정하는 기준입니다. 7d_click은 클릭 후 7일, 1d_view는 노출 후 1일입니다. 광고 매니저 화면은 계정 기본값으로 집계하는데, API 요청에서 action_attribution_windows를 명시하지 않으면 화면과 다른 기본값이 적용되어 숫자가 어긋납니다.

해결은 단순합니다. API 요청에 항상 attribution window를 명시하고, 그 값을 화면 설정과 일치시키면 두 숫자가 맞습니다. 더 중요한 건 이 값을 명시하는 순간 마케터가 한 가지를 깨닫는다는 점입니다. ROAS 5라는 숫자는 attribution window 설정 위에 올라간 숫자이지, 광고의 객관적 진실이 아니라는 것. 같은 캠페인도 7d_click과 1d_view로 받으면 전환 수가 꽤 달라집니다.

크리에이티브 메타데이터는 따로 붙여야 한다

성과 숫자는 insights에 있지만, 그 광고가 어떤 소재였는지는 insights에 없습니다. 이미지인지 영상인지, 어떤 카피였는지 같은 정보는 광고 노드의 creative 필드나 /adcreatives 엣지에서 가져와 ad_id를 기준으로 조인해야 합니다.

마케터가 이걸 굳이 합치는 이유는 크리에이티브 단위 분석 때문입니다. 어떤 썸네일이 CTR을 끌어올리는지, 어떤 카피 길이가 전환율과 상관있는지를 보려면 성과와 소재가 한 테이블에 있어야 합니다. 크리에이티브 피로도를 추적할 때도 같습니다. 같은 소재의 일자별 성과 추이를 보려면 ad_id에 크리에이티브 메타데이터가 붙어 있어야 합니다.

조인 키는 ad_id로 통일하는 게 안전합니다. 광고 이름은 운영 중에 바뀌기도 하고 중복되기도 하지만 ad_id는 불변입니다. 이름 기준으로 조인하면 어느 순간 행이 어긋나는데, 원인을 찾기가 까다롭습니다.

대용량 추출의 함정 — async 리포트와 rate limit

며칠치 몇 개 캠페인은 위 코드로 끝납니다. 문제는 계정 전체를 광고 단위로, 긴 기간을, 일자별로 받을 때입니다. 응답이 수만 행이 되면 동기 호출은 타임아웃으로 죽습니다.

Meta는 이걸 위해 비동기 리포트를 제공합니다. /insights에 POST로 작업을 등록하면 report_run_id를 돌려주고, 그 작업의 상태를 폴링하다가 완료되면 결과를 페이지 단위로 받아옵니다. 큰 추출은 반드시 이 비동기 경로로 가야 합니다. 동기 호출로 버티려다 매일 새벽 파이프라인이 깨지는 패턴을 자주 봅니다.

rate limit도 같이 만납니다. Meta는 광고 계정 단위로 호출량을 제한하고, 한도에 가까워지면 응답 헤더에 사용량을 실어 보냅니다. 안정적인 파이프라인은 이 헤더를 읽어 호출 속도를 조절하고, 한도를 넘으면 지수 백오프로 재시도합니다. 여러 계정을 도는 컨설팅 환경이라면 계정마다 한도가 따로 걸린다는 점을 이용해, 계정별로 호출을 분산하는 설계가 유리합니다.

파이프라인으로 묶을 때 정해야 할 것들

일회성 추출이 아니라 매일 도는 파이프라인이라면 몇 가지를 미리 정해둬야 뒤가 편합니다.

첫째는 재집계 윈도입니다. Meta의 전환 데이터는 과거 날짜도 며칠간 계속 갱신됩니다. 어제 데이터를 오늘 받고 끝내면 사흘 뒤에 추가된 전환을 놓칩니다. 그래서 보통 최근 N일(예: 7일)을 매일 다시 받아 덮어쓰는 방식으로 운영합니다. 이 재집계 윈도를 며칠로 둘지는 채널 특성과 전환 지연에 따라 정합니다.

둘째는 스키마 통일입니다. Meta만 받을 게 아니라면, 컬럼 이름과 단위를 다른 매체와 맞춰두는 게 나중을 살립니다. spend의 통화 단위, 날짜 형식, 전환 유형 명명을 첫날에 정해두지 않으면 매체가 늘 때마다 변환 코드가 누더기가 됩니다.

마치며

Meta Marketing API의 어려움은 코드가 아니라 개념에 있습니다. 토큰의 수명, attribution window가 숫자를 어떻게 바꾸는지, 전환 데이터가 배열로 온다는 것, 큰 추출은 비동기로 가야 한다는 것. 이 네 가지를 이해하면 나머지는 파라미터 조합입니다.

그리고 이 작업의 진짜 보상은 자동화가 아닙니다. 광고 매니저가 정해준 기준에서 벗어나, attribution window를 내가 골라 보고 채널을 같은 잣대로 비교하게 되는 것입니다. 그때부터 ROAS 보고서를 읽는 눈이 달라집니다.

참고

• Meta Marketing API — Insights 공식 문서
• Meta — System Users와 비즈니스 권한 관리
• Meta — Asynchronous Insights 리포트