Glowb Dev Docs
Admin APIMeta Marketing Insights

GET /ai/business/meta/campaigns

Meta 광고 캠페인 목록 조회 (멀티 광고계정 + Collab 매핑 표시)

캠페인 목록 조회

광고 계정의 캠페인 목록을 페이징 조회합니다. 각 캠페인 응답에는:

  • Collab 매핑 여부 (linked / linkedCollabNo) — 내부 Glowb Collab 과 연결됐는지
  • 대표 이미지 (representativeImageUrl) — 산하 광고 중 가장 최근 created_time 광고의 이미지
  • 광고목표 + 대표 KPI (objective / objectiveLabel / primaryMetric) — 메인 노출용. 판매→구매 수, 클릭 유도→링크 클릭 수 등 광고목표별 핵심 지표 1개
  • 실제 달성 결과 (result) — 매출(구매 전환 금액)·지출·ROAS. since/until 지정 시 그 기간 집계, 미지정 시 전체 누적
  • Meta 목표/최적화 (optimizationGoal / conversionEvent + 한글 라벨) — 산하 광고세트의 최적화 목표(예: 전환·전환값)와 전환 이벤트(예: 구매) 대표값
  • 하위 트리 (adsets → ads) — Meta Graph API nested edge 형식

가 한 번의 호출로 같이 반환됩니다.

production 환경에서 매시간 두 번 (:10 active batch — 최근 90일 일별 인사이트 갱신, :30 inactive backfill — PAUSED 캠페인 lifetime 보강) 이 5개 광고계정(글로우비/디웨더/리빙/Supera/건식건기식) 의 트리·일별 인사이트를 TB_META_OBJECT_SNAPSHOT / TB_META_INSIGHT_DAILY 에 적재하며 광고 cover 이미지도 함께 S3 백업합니다. 응답은 DB-first. 요청 기간이 적재 범위(최근 90일)를 벗어나면 Meta API 로 자동 fallback 후 DB upsert.

HTTP 요청

GET /ai/business/meta/campaigns
Authorization: Bearer {access_token}

Query Parameters

파라미터기본값권한설명
accountId(없음)ADMIN광고 계정 ID(act_xxx). 미지정 시 전체 광고계정 통합 조회. 기업 회원은 무시됨
status(없음)공통상태 필터 (ACTIVE, PAUSED 등). 대소문자 무시
q(없음)공통캠페인 이름 부분일치 (case-insensitive)
filterall공통Collab 매핑 필터. linked (O) / unlinked (X) / all
sortstartTime,desc공통정렬. 허용: name, status, objective, startTime, endTime, lastSyncedAt. NULL 은 항상 맨 뒤
since(없음)공통기간별 조회 시작일(YYYY-MM-DD). until 과 함께 지정 시 ① 운영기간이 [since, until] 과 겹치는 캠페인만 노출 ② result·primaryMetric 을 그 기간으로 집계. 둘 중 하나만 주면 무시
until(없음)공통기간별 조회 종료일(YYYY-MM-DD)

페이지네이션 없음 — 조건에 맞는 캠페인 전체를 한 번에 반환합니다. ADMIN 으로 전체 호출 시 글로우비 계정(약 1,070 캠페인 + 광고세트/광고 트리)의 응답이 수 MB 가 될 수 있으니 accountId / status / q 등으로 필터링하세요.

권한별 동작 차이

  • ADMIN: accountId + filter 자유. 미지정 시 5계정 전체.
  • 기업 회원: ADMIN 이 만든 매핑(Collab O ∪ Business X) 합집합 안의 캠페인만 조회 (응답에 광고계정 정보 없음 — 기업은 광고계정 개념 안 다룸). accountId 는 무시. filter 로 O/X 토글 가능.

기업 회원에게 노출되는 캠페인은 ADMIN 이 명시적으로 만든 두 종류 매핑의 합집합입니다 — (1) Collab ↔ 캠페인 매핑(O, linked=true), (2) Business ↔ 캠페인 직접 매핑(X, linked=false). 광고계정 단위 자동 추론은 없으므로, 매핑 0건이면 기업 화면은 비어 있습니다. 매핑 생성·삭제는 POST/DELETE /mapping(O 용) 및 POST/DELETE /business-mapping(X 용) 으로 ADMIN 이 수행.

예시

# ADMIN: 디웨더 계정의 Collab 미연결 캠페인만
GET /ai/business/meta/campaigns?accountId=act_1160065922750394&filter=unlinked

# ADMIN: 글로우비 계정에서 Collab 연결된 ACTIVE 캠페인만, 이름 검색
GET /ai/business/meta/campaigns?accountId=act_2916260795344961&filter=linked&status=ACTIVE&q=봄

# 기업 회원: 본인에게 연결된 캠페인 전체 (O + X 같이, 플래그로 구분)
GET /ai/business/meta/campaigns

# 기업 회원: O 만 (대시보드 "매핑된 캠페인" 탭)
GET /ai/business/meta/campaigns?filter=linked

# 기업 회원: X 만 (대시보드 "기타 매핑 안 된 캠페인" 탭)
GET /ai/business/meta/campaigns?filter=unlinked

# 기간별 조회: 5월 한 달 운영된 캠페인만 + result/primaryMetric 을 5월 기준 집계
GET /ai/business/meta/campaigns?since=2026-05-01&until=2026-05-31

Meta 는 캠페인에 "목표 매출 금액"을 설정값으로 받지 않습니다. 글로우비 캠페인은 대부분 자동 입찰(LOWEST_COST_WITHOUT_CAP)이라 "최소 ROAS" 같은 숫자 목표가 없습니다. 따라서 result 의 ROAS/매출은 실제 달성치(구매 action_values ÷ 지출)이고, "목표"성 정보는 optimizationGoal(무엇을 최적화하는지)·conversionEvent(어떤 전환을 추적하는지)·예산으로 표현됩니다.

응답

성공 응답 (200 OK)

응답의 data 는 캠페인 배열 (페이징 없음):

{
  "status": 200,
  "code": null,
  "message": "캠페인 목록 조회 완료",
  "data": [
    {
      "id": "120244131245240347",
      "name": "봄 시즌 프로모션",
      "status": "ACTIVE",
      "objective": "OUTCOME_TRAFFIC",
      "dailyBudget": "10000",
      "lifetimeBudget": null,
      "startTime": "2026-03-01T00:00:00+0000",
      "stopTime": null,
      "linked": true,
      "linkedCollabNo": 1523,
      "representativeImageUrl": "https://d3mp6eqt0w2808.cloudfront.net/img/meta/creative/image/120244131245240347-987654321",
      "objectiveLabel": "클릭 유도",
      "primaryMetric": {
        "label": "링크 클릭 수",
        "value": 1840,
        "unit": "건"
      },
      "result": {
        "revenue": 3250000.0,
        "spend": 812500.0,
        "roas": 4.0,
        "currency": "KRW"
      },
      "optimizationGoal": "OFFSITE_CONVERSIONS",
      "optimizationGoalLabel": "전환",
      "conversionEvent": "PURCHASE",
      "conversionEventLabel": "구매",
      "adsets": {
        "data": [
          {
            "id": "987654321",
            "name": "20대 여성 타겟",
            "status": "ACTIVE",
            "campaignId": "120244131245240347",
            "dailyBudget": "5000",
            "lifetimeBudget": null,
            "startTime": "2026-03-01T00:00:00+0000",
            "endTime": null,
            "optimizationGoal": "OFFSITE_CONVERSIONS",
            "optimizationGoalLabel": "전환",
            "conversionEvent": "PURCHASE",
            "conversionEventLabel": "구매",
            "representativeImageUrl": "https://d3mp6eqt0w2808.cloudfront.net/img/meta/creative/image/...",
            "ads": {
              "data": [
                {
                  "id": "111222333",
                  "name": "스킨케어 광고 #1",
                  "status": "ACTIVE",
                  "adsetId": "987654321",
                  "campaignId": "120244131245240347",
                  "createdTime": "2026-03-01T00:00:00+0000",
                  "updatedTime": "2026-03-15T00:00:00+0000",
                  "imageUrl": "https://d3mp6eqt0w2808.cloudfront.net/img/meta/creative/image/111222333-creativeXYZ",
                  "instagramPermalinkUrl": "https://www.instagram.com/p/Cabcde12345/"
                }
              ],
              "paging": null
            }
          }
        ],
        "paging": null
      }
    }
  ]
}

응답 필드 설명

필드타입설명
idString캠페인 ID
nameString캠페인명
statusString상태 (ACTIVE, PAUSED, DELETED, ARCHIVED)
objectiveString캠페인 목표 (예: OUTCOME_TRAFFIC, OUTCOME_AWARENESS)
dailyBudgetString일일 예산. Meta 원시 문자열 — 통화 최소 단위(KRW는 원 그대로, 추가 변환 불필요). 미설정 시 null
lifetimeBudgetString총 예산. 단위는 dailyBudget 과 동일. 미설정 시 null
startTime / stopTimeString시작/종료 시각
linkedbooleanGlowb Collab 과 매핑됐는지 (O/X 표시용)
linkedCollabNoInteger?매핑된 Collab 번호. linked=false 면 null
representativeImageUrlString?캠페인 대표 이미지 — 산하 광고 중 가장 최근 created_time 광고의 이미지(없으면 cover). 광고가 없거나 모두 백업 미완이면 null
objectiveLabelString?광고목표 한글 라벨 (판매/클릭 유도/동영상 조회/잠재고객/앱 설치/참여/인지). objective 가 null/미지원이면 null
primaryMetricObject?광고목표별 대표 KPI 1개 — { label, value, unit }. 기본 전체 누적, since/until 지정 시 해당 기간 (attribution_window=7d_click 기준). 적재된 인사이트가 없으면 value=0
resultObject?실제 달성 결과 — { revenue, spend, roas, currency }. revenue·spend·roas 는 문자열이 아닌 숫자(number), currency 는 String(예: "KRW"). revenue=구매 전환 금액(action_values 의 purchase, EQUALS 매칭 합) · spend=지출 합 · roas=revenue/spend(소수 2자리, 지출 0이면 null, 매출만 0이면 0.0). 금액 단위는 통화 기본 단위 그대로(KRW면 원 — 예: revenue: 1019300.0 = 1,019,300원, ÷100 하지 말 것). since/until 지정 시 해당 기간 집계
optimizationGoal / optimizationGoalLabelString?산하 광고세트 최적화 목표 대표값(최빈)과 한글 라벨. 예: OFFSITE_CONVERSIONS→"전환", VALUE→"전환값(매출)". 광고세트 없거나 미설정이면 null
conversionEvent / conversionEventLabelString?전환 이벤트 대표값(promoted_object.custom_event_type)과 한글 라벨. 예: PURCHASE→"구매". 미설정이면 null
adsets.data[]MetaAdSetDto[]하위 광고세트들 (각 광고세트에도 representativeImageUrl 및 ads 임베딩)
adsets.pagingObject페이징 정보 (현재 항상 null)

프론트 구현 참고

  • 한글 라벨은 백엔드가 내려줍니다. optimizationGoalLabel / conversionEventLabel / objectiveLabel 을 그대로 표시하면 됩니다(프론트에서 enum→한글 매핑 불필요). 라벨이 null 이면 미지원/미설정이므로 원본 코드값(optimizationGoal 등)으로 폴백하거나 숨기면 됩니다.
  • 타입 주의: 예산(dailyBudget/lifetimeBudget)·KPI 라벨/단위는 문자열이고, result.revenue/spend/roas 와 primaryMetric.value 는 숫자입니다.
  • "목표 매출 금액" 같은 숫자 목표는 없습니다 — Meta 미제공. result 는 실제 달성치, optimizationGoal/conversionEvent 가 "목표/최적화" 표시용입니다.
  • 광고(AD) 레벨엔 목표(optimizationGoal/conversionEvent)·result 가 없습니다. 목표는 캠페인·광고세트, result(매출/ROAS)는 캠페인 레벨에만 내려갑니다.

MetaAdSetDto 응답 필드 (nested)

필드타입설명
optimizationGoal / optimizationGoalLabelString?광고세트 최적화 목표(optimization_goal)와 한글 라벨
conversionEvent / conversionEventLabelString?전환 이벤트(promoted_object.custom_event_type)와 한글 라벨
representativeImageUrlString?광고세트 대표 이미지 — 산하 광고 중 가장 최근 created_time 광고의 이미지(또는 비디오 cover)
ads.data[]MetaAdDto[]하위 광고들

MetaAdDto 응답 필드 (nested)

필드타입설명
imageUrlString?광고 이미지 URL (S3/CloudFront) — 광고 유형 무관 단일 필드. 이미지 광고면 원본, 비디오 광고면 cover 풀해상도(1080×1080). 백업 미완 또는 creative 없음이면 null
instagramPermalinkUrlString?Instagram 게시물 permalink URL. 광고가 기존 Instagram 게시물을 promote 한 경우 채워짐. 외부 링크/Facebook only 광고는 null

사용 시나리오 (ADMIN UI)

[ 광고계정 드롭다운 ] (accountId)
   ▼
[ 탭: 연결된 캠페인 | 기타 ]   ← filter=linked / unlinked
   ▼
[ 캠페인 카드 그리드 ]
   - representativeImageUrl 썸네일
   - linked ? "O Collab #1523" : "X 미연결"
   - 클릭 → 상세 (adsets / ads 트리)

에러 응답

상태 코드설명
401인증 실패

API 테스트

GET /ai/business/meta/insights

Meta 광고 계정 전체 인사이트 조회 (ADMIN · 기업 회원 공통)

GET /ai/business/meta/campaigns/{campaignId}/adsets

Meta 광고세트 목록 조회 (기업 회원용)

On this page

캠페인 목록 조회
HTTP 요청
Query Parameters
권한별 동작 차이
예시
응답
성공 응답 (200 OK)
응답 필드 설명
MetaAdSetDto 응답 필드 (nested)
MetaAdDto 응답 필드 (nested)
사용 시나리오 (ADMIN UI)
에러 응답
API 테스트