Meta Ads API 입문: 클릭과 전환을 구분해 첫 보고서 만들기
Meta 광고 데이터를 조회하기 전에 클릭 종류와 계정 통화, 전환 배열의 뜻을 정리합니다. 앱과 토큰 준비, Python으로 캠페인 보고서를 CSV로 받는 코드, 광고 관리자와 숫자가 다를 때 맞추는 순서까지 설명합니다.

세 줄로 먼저 읽기
- 첫 조회는 계정 하나와 기간, 행 단위를 정하고 광고 관리자와 같은 조건으로 비교합니다.
- inlinelinkclicks는 Meta 안팎으로 가는 링크 클릭이고 outbound_clicks는 Meta 밖으로 나가는 클릭이며, spend는 계정 통화 금액이라 100만으로 나누지 않습니다.
- 전환은 actions 배열에서 actiontype 하나를 골라 쓰고 purchase와 omnipurchase처럼 범위가 겹치는 유형은 더하지 않습니다.
Meta Marketing API는 프로그램이 Facebook과 Instagram 광고 정보를 요청하고 관리하는 연결 방식입니다. 그 가운데 성과 보고를 조회하는 부분을 Insights API라고 부릅니다.
보고서를 한 번 내려받는 일이라면 광고 관리자의 내보내기로 충분합니다. API는 여러 계정의 자료를 반복해서 합치거나 정기적으로 갱신할 때 씁니다. 아래에서는 계정 하나의 캠페인 성과를 조회하고, 비용과 전환 숫자가 광고 관리자와 같은 뜻인지 맞춰 보는 과정을 순서대로 설명합니다.
먼저 보고서 조건을 정합니다
코드를 쓰기 전에 무엇을 어떤 단위로 받을지 정해 둬야 나중에 광고 관리자와 비교할 수 있습니다.
첫 보고서에서 정할 여섯 가지
1. 계정조회 권한이 있는
광고 계정 ID 하나
2. 기간2026-09-21부터
2026-09-27까지처럼
3. 행 단위캠페인 하나의
기간 합계
4. 기본 지표노출, 링크 클릭
비용
5. 전환웹 구매처럼
비교할 유형 하나
6. 대조 대상같은 조건으로 연
광고 관리자 보고서
ID는 이름과 별개인 식별 번호입니다. 광고 계정을 조회할 때는 숫자 앞에 act_가 붙은 계정 ID를 씁니다.
조회 데이터는 세 종류입니다
Insights API로 받는 값은 성격에 따라 세 가지로 나뉩니다. 필드는 가져올 항목의 이름이고, Breakdown(세분화)은 성과를 나누는 기준입니다.
조회 데이터의 세 종류
| 항목 | |||
|---|---|---|---|
| 예시 | 캠페인 이름 상태, 예산 | 노출, 클릭 비용, 전환 | 연령, 성별 게재 위치 |
| 주의할 점 | 성과와 다른 필드나 요청이 필요 | 지표 정의와 기간 일치 | 지원하는 조합만 쓸 수 있음 |
세 종류의 필드 목록과 요청 방식은 Insights API 개요에 있습니다.
계정 접근 준비
API를 직접 쓰려면 Meta 개발자 앱을 만들고, 대상 광고 계정에 접근할 인증을 준비합니다. 앱은 API 사용과 권한을 관리하는 단위입니다.
API 조회 전 준비 순서
1. 개발자 앱이용 사례에서
Marketing API 선택
2. 권한보고서 읽기는 ads_read
요청에 맞는 권한 추가
3. 자산 할당인증한 사용자나 시스템 사용자에게
대상 광고 계정 할당
4. 접근 수준앱 사용 대상에 맞는
검수와 비즈니스 인증
5. API 버전코드와 SDK에서 쓸
지원 버전 하나
자기 회사 계정을 조회하는 앱과 다른 사업자의 계정을 다루는 앱은 요구사항이 다릅니다. 권한마다 붙는 Standard와 Advanced 접근은 호출량을 정하는 Marketing API Access Tier와 별개이고, 현재 문서는 Access Tier를 Limited와 Full로 나눕니다. 이름이 비슷해도 서로 다른 설정이어서, 앱 대시보드에서 두 항목을 따로 봅니다. 자세한 기준은 권한과 접근 안내에 있습니다.
액세스 토큰은 비밀 인증 정보입니다
액세스 토큰은 API 요청을 허용하는 인증 정보입니다. 시스템 사용자는 사람이 로그인하는 계정 대신 프로그램에 자산 접근을 주는 구성입니다. 테스트할 때와 운영할 때 쓰는 토큰이 다릅니다.
테스트용 토큰과 운영용 토큰
| 항목 | ||
|---|---|---|
| 사람이 로그인한 계정 기준 | 제공 | 제공하지 않음 |
| 정기 자동 조회에 사용 | 제공하지 않음 | 제공 |
| 권한 회수나 무효화 뒤에도 사용 | 제공하지 않음 | 제공하지 않음 |
토큰에는 필요한 역할과 자산만 할당하고, 만료와 오류를 볼 담당자를 정합니다. 모든 자동화에 관리자 역할을 한꺼번에 주지 않습니다.
토큰 값은 코드나 URL, 화면 캡처에 넣어 공유하지 않습니다. 아래 예시는 토큰을 환경 변수에서 읽습니다. 환경 변수는 실행할 프로그램에 전달하는 설정값입니다. 토큰이 이미 노출됐다면 담당자가 폐기하고 다시 발급합니다. 토큰 종류와 유효 기간은 Meta 액세스 토큰 안내에 있습니다.
클릭수와 웹사이트 방문은 같지 않습니다
Meta는 클릭을 여러 필드로 나눠 돌려줍니다. 같은 광고에서도 어느 필드를 쓰느냐에 따라 숫자가 다릅니다.
클릭 관련 필드의 집계 범위
| 필드 | |||
|---|---|---|---|
| clicks | 제공 | 제공 | 제공하지 않음 |
| inline_link_clicks | 제공하지 않음 | 제공 | 제공하지 않음 |
| outbound_clicks | 제공하지 않음 | 제공하지 않음 | 제공하지 않음 |
| actions의 landing_page_view | – | – | 제공 |
clicks는 링크 말고 다른 광고 상호작용까지 포함한 전체 클릭이고, inline_link_clicks는 Meta 안팎의 목적지로 가는 링크 클릭입니다. outbound_clicks는 Meta 밖으로 나가는 링크 클릭이지만, 이 값도 페이지 로딩 완료나 GA4 세션 수와는 다릅니다. 그래서 링크 클릭 100회를 웹사이트가 100번 열린 것으로 적지 않습니다.
outbound_clicks는 배열로 돌아올 수 있어서 clicks처럼 숫자 하나로 바로 계산하지 않습니다. 다른 매체의 클릭과 비교할 때는 어느 필드를 썼고 목적지가 어디인지 함께 적습니다.
기본 지표와 단위 맞추기
| 지표 | 필드 | 뜻 |
|---|---|---|
| 노출 | impressions | 광고가 표시된 횟수 |
| 도달 | reach | 조회 범위에서 중복을 뺀 사람 수 추정치 |
| 빈도 | frequency | 노출 ÷ 도달 |
| 비용 | spend | 계정 통화 기준 금액 |
| 링크 클릭률 | inline_link_click_ctr | 링크 클릭 기준 백분율 |
| 전체 클릭당 비용 | cpc | 전체 클릭 기준 |
| 노출 1,000회당 비용 | cpm | 비용 ÷ 노출 × 1,000 |
spend가 "15000"이고 계정 통화가 KRW면 15,000원, USD면 15,000달러입니다. Google Ads의 cost_micros와 달리 Meta 비용은 100만으로 나누지 않습니다. 비용 옆에는 늘 계정 통화를 함께 적습니다.
날짜별이나 캠페인별로 받은 값을 합칠 때는 지표마다 처리가 다릅니다.
날짜별 값을 합칠 때 지표별 처리
| 지표 | ||
|---|---|---|
| 노출, 비용, 링크 클릭 | 제공 | 제공하지 않음 |
| 도달 | 제공하지 않음 | 제공 |
| 빈도 | 제공하지 않음 | 제공 |
| 클릭률, CPC, CPM | 제공하지 않음 | 합친 값으로 다시 계산 |
필드별 정의는 Insights 필드 정의에 있습니다.
전환 배열에서 필요한 유형을 고릅니다
배열은 여러 항목을 묶은 목록입니다. actions에는 행동 수가, action_values에는 그 행동의 가치가 들어 있고, 각 항목의 종류는 action_type으로 구분합니다. 응답은 아래와 같은 모양입니다.
{
"spend": "15000",
"actions": [
{"action_type": "link_click", "value": "30"},
{"action_type": "offsite_conversion.fb_pixel_purchase", "value": "3"}
],
"action_values": [
{"action_type": "offsite_conversion.fb_pixel_purchase", "value": "60000"}
]
}이 예시 응답에서 웹 구매 항목만 골라 계산하면 아래 네 숫자가 나옵니다. 구매가치가 비용과 같은 통화로 기록됐다고 가정한 계산입니다.
예시 응답에서 웹 구매만 골라 계산한 값
3건웹 구매fb_pixel_purchase
60,000원구매가치action_values
5,000원구매당 비용15,000 ÷ 3
4배ROAS60,000 ÷ 15,000
웹 구매, 전체 구매, 앱 구매는 범위가 겹칠 수 있습니다. purchase, omni_purchase, offsite_conversion.fb_pixel_purchase처럼 이름이 비슷한 값을 모두 더하면 같은 구매가 두 번 이상 들어갑니다. 광고 관리자에서 비교할 열과 실제 응답을 나란히 놓고 유형을 하나 고릅니다. 유형 사이의 겹침은 행동 값의 계층과 세분화에 설명돼 있습니다.
배열에 원하는 항목이 아예 없으면 실제 0건이 아니라 값이 오지 않은 것으로 남깁니다. 광고 관리자의 '결과' 열은 캠페인의 성과 목표에 따라 바뀌어서, 판매 캠페인의 결과 열도 웹 구매가 아닐 수 있습니다.
응답 한 행을 보고서 행으로 바꾸는 코드
아래 코드는 응답 한 행에서 비용과 웹 구매를 꺼내 구매당 비용과 ROAS를 계산합니다. meta_parse.py로 저장해 두면 다음 절의 조회 코드가 이 파일을 불러 씁니다. 이 파일은 외부 패키지 없이 실행됩니다.
from decimal import Decimal
PURCHASE = "offsite_conversion.fb_pixel_purchase"
def action_value(items, action_type):
if items is None:
return None
matches = [x for x in items if x.get("action_type") == action_type]
if len(matches) > 1:
raise ValueError("같은 행동 유형이 여러 개 있습니다. 세분화 조건을 다시 보세요.")
if not matches or matches[0].get("value") is None:
return None
return Decimal(str(matches[0]["value"]))
def ratio(numerator, denominator):
if numerator is None or denominator is None or denominator == 0:
return None
return numerator / denominator
def report_row(row):
spend = Decimal(str(row["spend"])) if row.get("spend") is not None else None
purchases = action_value(row.get("actions"), PURCHASE)
value = action_value(row.get("action_values"), PURCHASE)
return {
"campaign_id": row.get("campaign_id"),
"campaign_name": row.get("campaign_name"),
"currency": row.get("account_currency"),
"date_start": row.get("date_start"),
"date_stop": row.get("date_stop"),
"spend": spend,
"impressions": row.get("impressions"),
"link_clicks": row.get("inline_link_clicks"),
"purchases": purchases,
"purchase_value": value,
"purchase_cpa": ratio(spend, purchases),
"roas": ratio(value, spend),
}report_row가 한 행을 처리하는 순서
1. 비용spend 문자열을
Decimal 금액으로
2. 구매 수와 가치배열에서 웹 구매 항목만
없으면 None
3. CPA와 ROAS비용 ÷ 구매 수
구매가치 ÷ 비용
4. 나눌 수 없을 때구매 0건이나 비용 0원이면
0이 아니라 None
Decimal은 금액 계산에 쓰는 십진수 형식이고, None은 값이 오지 않았거나 계산할 수 없다는 표시입니다. 구매 0건이나 비용 0원이라 나눌 수 없는 값을 0으로 채우면, 보고서에서 실제로 성과가 0인 캠페인과 구분이 안 됩니다. 원시 값이 숫자로 바꿀 수 없는 문자열이면 코드가 오류를 내고 멈추므로, 그 행의 응답을 열어 봅니다.
조회 코드는 인증 준비가 끝난 뒤 실행합니다
다음은 공식 Python SDK로 캠페인 보고서를 받아 CSV로 저장하는 예시입니다. SDK는 API 호출을 돕는 코드 묶음이고, CSV는 표의 행과 열을 담는 텍스트 파일입니다. 앞의 meta_parse.py와 같은 폴더에 meta_report.py로 저장합니다.
조회 코드 실행 순서
1. SDK 설치실행할 Python 환경에
facebook_business
2. 환경 변수 다섯 개앱 ID, 앱 시크릿, 토큰
계정 ID, API 버전
3. 실행python3 meta_report.py
4. CSV 확인N개 행 저장 문구와
meta_report.csv 파일
5. 광고 관리자와 대조통화, 기간, 캠페인 ID
구매 유형
환경 변수 이름은 META_APP_ID, META_APP_SECRET, META_ACCESS_TOKEN, META_AD_ACCOUNT_ID, META_API_VERSION입니다. META_AD_ACCOUNT_ID에는 act_까지 넣고, META_API_VERSION에는 담당자가 현재 지원 여부와 SDK 호환성을 확인한 버전을 넣습니다. SDK 설치 방법은 공식 Python SDK 저장소에 있습니다.
import csv
import os
from pathlib import Path
from facebook_business.api import FacebookAdsApi
from facebook_business.adobjects.adaccount import AdAccount
from meta_parse import report_row
FacebookAdsApi.init(
app_id=os.environ["META_APP_ID"],
app_secret=os.environ["META_APP_SECRET"],
access_token=os.environ["META_ACCESS_TOKEN"],
api_version=os.environ["META_API_VERSION"],
)
account = AdAccount(os.environ["META_AD_ACCOUNT_ID"])
fields = [
"campaign_id", "campaign_name", "account_currency",
"date_start", "date_stop", "impressions", "inline_link_clicks",
"spend", "actions", "action_values",
]
params = {
"level": "campaign",
"time_range": {"since": "2026-09-21", "until": "2026-09-27"},
"use_unified_attribution_setting": True,
"limit": 100,
}
rows = [report_row(dict(row)) for row in account.get_insights(fields=fields, params=params)]
if not rows:
print("조회 결과가 없습니다. 계정, 기간, 필터를 다시 보세요.")
else:
output = Path("meta_report.csv")
with output.open("x", newline="", encoding="utf-8-sig") as f:
writer = csv.DictWriter(f, fieldnames=list(rows[0]))
writer.writeheader()
writer.writerows(rows)
print(f"{len(rows)}개 행 저장: {output.resolve()}")python3 meta_report.py로 실행하면 현재 폴더에 meta_report.csv가 생깁니다. 같은 이름의 파일이 이미 있으면 덮어쓰지 않고 멈추므로, 기존 보고서를 옮기거나 파일 이름을 바꾼 뒤 다시 실행합니다. SDK는 결과를 순회하면서 다음 페이지를 알아서 가져오기 때문에, limit=100은 한 번에 받는 행 수이고, 100행이 넘는 보고서도 끝까지 받습니다.
조회 기간은 params의 time_range에서 바꿉니다. CSV에서는 None이 빈칸으로 저장되어 0과 구분됩니다. 노출과 링크 클릭은 문자열로 받을 수 있어서, 엑셀이나 다른 코드에서 계산하기 전에 숫자 형식으로 바꿉니다.
이 코드는 계정 하나와 짧은 기간을 조회하는 예시입니다. 여러 계정을 정기적으로 돌리려면 요청 한도 관리, 재시도와 중복 저장 방지, 큰 보고서의 비동기 처리, 실패 알림을 더합니다. 비동기 처리는 요청하자마자 결과를 받는 대신, 보고서 생성이 끝난 뒤 결과를 따로 가져오는 방식입니다.
기여 기간과 보고 날짜 맞추기
기여 기간은 광고를 보거나 누른 뒤 며칠 안의 전환까지 그 광고의 성과로 인정할지 정한 기간입니다. 광고 관리자와 숫자를 맞추려면 기여와 날짜에 관한 매개변수 세 개를 봅니다.
전환 숫자를 바꾸는 매개변수 세 개
| 항목 | |||
|---|---|---|---|
| 정하는 것 | 광고 세트의 기여 설정 사용 | 1d_click, 7d_click 같은 기간 | 노출일과 전환일 가운데 어느 날 |
| 위 조회 코드 | True로 사용 | – | – |
위 코드는 use_unified_attribution_setting=True로 광고 세트 수준의 기여 설정을 따르게 했습니다. 기간별로 비교하려면 지원되는 action_attribution_windows 값을 골라 그 조건으로 조회하고, 보고서에도 어떤 기간인지 적습니다. 모든 계정의 조회 조건을 7일 클릭과 1일 조회 같은 기간 하나로 일괄 바꾸지 않습니다.
action_report_time은 전환을 노출이 일어난 날에 기록할지, 전환이 일어난 날에 기록할지 정합니다. 광고 관리자와 비교할 때는 이 조건도 맞춥니다. 1d_click과 7d_click은 기간이 겹치므로, 두 값을 더해 전체 전환을 만들지 않습니다.
세분화는 하나씩 추가합니다
| 목적 | 세분화 필드 |
|---|---|
| 연령과 성별 | age, gender |
| 플랫폼과 게재 위치 | publisher_platform, platform_position |
| 기기 종류 | 필요한 수준에 맞는 device_platform 또는 impression_device |
세분화는 모든 조합이 허용되지 않고, 조합에 따라 전환 지표가 빠지기도 합니다. 그래서 한꺼번에 여러 개를 넣지 않고 하나씩 더해 가며 결과를 봅니다.
세분화를 더하는 순서
1. 세분화 없이 조회캠페인 합계를
광고 관리자와 맞춤
2. 하나 추가age, gender처럼
세분화 하나
3. 행과 지표 보기행이 없거나 0이면
지원 조합인지부터
4. 다음 세분화앞 결과가 맞은 뒤
하나 더
도달과 고유 사용자 지표는 세분화 값별이나 날짜별 값을 더해 전체 값으로 쓰지 않습니다. 과거 자료를 얼마나 거슬러 조회할 수 있는지와 지원 버전은 지표와 요청 조건마다 다르며, 제한과 권장사항과 변경 안내에 정리돼 있습니다.
오류가 나면 어디부터 볼까요?
| 증상 | 다음에 볼 곳 |
|---|---|
ModuleNotFoundError | 실행 중인 Python 환경에 SDK가 설치됐는지 |
환경 변수 이름의 KeyError | 그 설정이 프로그램에 전달됐는지(값은 출력하지 않음) |
| 인증 오류 | 토큰이 유효한지, 필요한 권한이 있는지 |
| 권한 오류 | 앱 접근 수준과 대상 광고 계정의 자산 할당 |
| 결과 없음 | 계정, 기간, 필터, 그 기간의 실제 광고 집행 |
| 구매만 비어 있음 | 응답의 행동 유형, 기여 조건, 값이 오지 않았는지 |
FileExistsError | 같은 이름의 CSV가 있는지, 저장 위치 |
AI에게 오류를 물어볼 때는 비밀값을 지운 오류 코드와 실행한 단계, SDK 버전과 요청 필드만 붙여 넣고 인증 파일 전체는 넣지 않습니다.
오류 없이 실행됐는데 합계가 광고 관리자와 다르면 아래 순서로 조건을 하나씩 맞춥니다.
합계가 광고 관리자와 다를 때 맞추는 순서
1. 계정과 통화같은 계정 ID인지
KRW인지 USD인지
2. 기간과 시간대시작일과 종료일
계정 시간대
3. 행 단위캠페인 합계인지
날짜별인지
4. 전환 정의같은 action_type인지
겹치는 유형을 더했는지
5. 기여와 보고 날짜기여 설정과
action_report_time
다른 매체 자료와 합치기 전에
API로 받은 숫자는 단위와 뜻을 붙여 둬야 다른 매체와 합칠 때 틀리지 않습니다. USD 계정에서 비용 "100", 링크 클릭 20, 외부 클릭 12가 나오고 구매 항목은 응답에 없었다면 이렇게 적습니다.
같은 응답을 보고서에 옮기는 두 방식
| 항목 | ||
|---|---|---|
| 비용 | 100원 | 100달러 (계정 통화 USD) |
| 클릭 | 20명 방문 | 링크 클릭 20회 외부 클릭 12회 |
| 구매 | 0건 | 값 없음 (응답에 항목 없음) |
다른 매체 자료와 합칠 때는 매체 이름, 계정 ID, 캠페인 ID, 날짜를 함께 보관해야 나중에 어느 숫자가 어디서 왔는지 다시 찾을 수 있습니다.
3줄 요약
-
첫 조회는 계정 하나와 기간, 행 단위를 정하고 광고 관리자와 같은 조건으로 비교합니다.
-
inline_link_clicks는 Meta 안팎으로 가는 링크 클릭이고 outbound_clicks는 Meta 밖으로 나가는 클릭이며, spend는 계정 통화 금액이라 100만으로 나누지 않습니다.
-
전환은 actions 배열에서 action_type 하나를 골라 쓰고 purchase와 omni_purchase처럼 범위가 겹치는 유형은 더하지 않습니다.

제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
Meta API의 inline_link_clicks가 100이면 외부 웹사이트가 100번 열렸다는 뜻인가요?

새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.
이 글이 도움이 되었나요?
메일, 회의록, 리포트처럼 반복되는 일을 AI로 자동화하는 순서와 안전장치를 다룹니다
코스 전체 보기 →