본문으로 건너뛰기

캠페인 성과 조회하기

특정 기간 동안 발송된 캠페인의 성과 집계 수치를 API로 조회하는 방법을 설명합니다. 블럭스 담당자에게 문의하여 발급받은 secret key를 사용해서 조회할 수 있습니다.

개요​

  • 콘솔의 캠페인 통계 페이지 "데이터 다운로드" 버튼으로 받을 수 있는 데이터와 동일한 발송/오픈/전환/매출 집계 수치를 API로 자동 수신할 수 있습니다.
  • 내부 BI/리포트 자동화, 광고 효율 모니터링 등에 활용할 수 있습니다.
  • 조회 단위는 캠페인 + 캠페인 내 발송 회차(task) 입니다. 한 캠페인이 여러 번 발송됐다면 task가 여러 개로 분리되어 반환됩니다.

조회 API​

엔드포인트​

GET https://api.blux.ai/prod/v2/applications/{APPLICATION_ID}/campaigns/metrics

인증​

요청 시 Authorization 헤더에 발급받은 secret key를 포함해야 합니다:

Authorization: {SECRET_KEY}

쿼리 파라미터​

파라미터타입필수설명
task_fromstring (ISO 8601)필수조회 시작 일시 (inclusive)
task_tostring (ISO 8601)필수조회 종료 일시 (exclusive)
campaign_schedule_typestring선택캠페인 종류 필터. once, recurring, api_trigger 중 하나. 미지정 시 모든 종류를 합쳐서 반환합니다.
  • task_from과 task_to 사이의 기간은 최대 180일까지 지원됩니다.
  • task가 task_from <= scheduled_at < task_to 범위에 들어가는 캠페인이 응답에 포함됩니다.

응답​

성공 시:

{
  "campaigns": [
    {
      "_id": "664cb3d2e2c8a8f0c9a1b2c3",
      "name": "5월 신상 알림",
      "tags": ["promotion"],
      "schedule_type": "once",
      "conversion": { ... },
      "is_ab_test": false,
      "tasks": [
        {
          "_id": "664cb40fe2c8a8f0c9a1b2d1",
          "campaign_id": "664cb3d2e2c8a8f0c9a1b2c3",
          "scheduled_at": "2026-05-20T01:00:00.000Z",
          "sent_at": "2026-05-20T01:00:08.000Z",
          "channel": "alimtalk",
          "sent_count": 1000,
          "received_count": 980,
          "open_count": 320,
          "click_count": 75,
          "purchase_count": 18,
          "purchase_count_by_click": 18,
          "purchase_count_by_open": 42,
          "purchase_count_by_received": 55,
          "revenue": 540000,
          "revenue_currency": "KRW",
          "revenue_by_click": { "value": 540000, "currency": "KRW" },
          "revenue_by_open": { "value": 1260000, "currency": "KRW" },
          "revenue_by_received": { "value": 1650000, "currency": "KRW" },
          "cost": 9800,
          "cost_currency": "KRW",
          "sent_user_count": 1000,
          "received_user_count": 980,
          "open_user_count": 305,
          "click_user_count": 72,
          "purchase_user_count_by_click": 17,
          "purchase_user_count_by_open": 40,
          "purchase_user_count_by_received": 52,
          "open_rate": 0.3265,
          "conversion_rate": 0.0184,
          "roas": 55.10
        }
      ]
    }
  ]
}

필드 설명​

캠페인 단위​

필드타입설명
_idstring캠페인 ID
namestring캠페인 이름
tagsstring[]콘솔에서 부여한 태그
schedule_typestring캠페인 발송 종류 (once, recurring, api_trigger)
conversionobject전환 판정 설정. event_type(전환으로 집계할 이벤트 타입), window_unit(h: 시간, d: 일), window_amount(전환 기한), condition(추가 조건, 선택) 포함
is_ab_testbooleanA/B 테스트 캠페인 여부
tasksarray발송 회차별 성과 집계. 아래 task 단위 필드 참고

task 단위 (발송 회차)​

필드타입설명
_idstringtask ID (발송 회차 ID)
campaign_idstring소속 캠페인 ID
scheduled_atstring (ISO 8601)발송 예약 시각. 일자별로 집계하려면 이 값을 기준으로 그룹화하세요
sent_atstring (ISO 8601)실제 발송 시작 시각. 발송 시작 전에는 누락될 수 있습니다
channelstring발송 채널 (alimtalk, friendtalk, sms, rcs, app_push, email, kakao_brand_message, webhook)
sent_countnumber발송 시도 수 (중복 O)
received_countnumber수신 성공 수
open_countnumber오픈 수
click_countnumber클릭 수
purchase_countnumber전환 수. 캠페인의 전환 집계 기준(클릭·오픈·수신)에 따라 아래 purchase_count_by_* 중 해당하는 값
purchase_count_by_clicknumber클릭 기준 전환 수
purchase_count_by_opennumber오픈 기준 전환 수
purchase_count_by_receivednumber수신 기준 전환 수
revenuenumber전환 매출 합계. 캠페인의 전환 집계 기준에 따라 아래 revenue_by_* 중 해당하는 값
revenue_currencystring매출 통화 (KRW)
revenue_by_clickobject클릭 기준 전환 매출. { "value": number, "currency": string } 형태
revenue_by_openobject오픈 기준 전환 매출. 형태 동일
revenue_by_receivedobject수신 기준 전환 매출. 형태 동일
costnumber발송 비용 합계
cost_currencystring비용 통화 (KRW)
sent_user_countnumber발송 시도 회원 수 (중복 X)
received_user_countnumber수신 성공 회원 수 (중복 X)
open_user_countnumber오픈 회원 수 (중복 X)
click_user_countnumber클릭 회원 수 (중복 X)
purchase_user_count_by_clicknumber클릭 기준 전환 회원 수 (중복 X)
purchase_user_count_by_opennumber오픈 기준 전환 회원 수 (중복 X)
purchase_user_count_by_receivednumber수신 기준 전환 회원 수 (중복 X)
fallback_messageobject대체 발송 성과 집계. 대체 발송이 없으면 누락됩니다. 내부에 channel·sent_count·received_count 등 위와 동일한 지표 구조를 가집니다
open_ratenumber오픈율. open_count / received_count. received_count가 0이면 0
conversion_ratenumber전환율. purchase_count / received_count. received_count가 0이면 0
roasnumberROAS (Return on Ad Spend). revenue / cost. cost가 0이면 0

채널별 추가 필드(sms_type, rcs_type, friendtalk_type, kakao_brand_message_type, kakao_friend_received_count, kakao_non_friend_received_count 등)가 채널에 따라 함께 반환될 수 있습니다.

제한 사항​

  • 조회 기간 (task_to − task_from)은 최대 180일까지 지원됩니다. 더 긴 기간이 필요하면 호출을 분할하세요.
  • 응답에는 페이지네이션이 없습니다. 한 번에 기간 내 모든 캠페인이 반환되므로, 활성 캠페인이 많은 application은 기간을 짧게 잡으세요.
  • 응답 시점에 따라 발송 직후의 오픈/전환/매출 수치는 아직 집계가 반영되지 않을 수 있습니다.

상태 코드​

코드설명
200 OK정상 응답
400 Bad Request필수 query 파라미터 누락, 형식 오류, 또는 기간 180일 초과
401 Unauthorized인증 실패 (secret key 오류, 또는 다른 application의 키 사용)
404 Not Found잘못된 application_id
500 Internal Server Error서버 내부 오류

테스트 예시​

curl -G "https://api.blux.ai/prod/v2/applications/abcd1234/campaigns/metrics" \
  -H "Authorization: xxxxxxxx" \
  --data-urlencode "task_from=2026-05-01T00:00:00.000Z" \
  --data-urlencode "task_to=2026-05-28T00:00:00.000Z"

특정 종류의 캠페인만 조회하려면:

curl -G "https://api.blux.ai/prod/v2/applications/abcd1234/campaigns/metrics" \
  -H "Authorization: xxxxxxxx" \
  --data-urlencode "task_from=2026-05-01T00:00:00.000Z" \
  --data-urlencode "task_to=2026-05-28T00:00:00.000Z" \
  --data-urlencode "campaign_schedule_type=api_trigger"

자주 묻는 질문 (FAQ)​

Q. 일자별로 집계해서 받고 싶은데요. A. 현재는 캠페인 + 발송 회차(task) 단위로만 반환합니다. 각 task의 scheduled_at을 일자로 잘라 합산하면 일자별 집계를 만들 수 있습니다.

Q. 캠페인 단위 한 줄로 모아서 받고 싶은데요. A. tasks[]를 더해서 모아주는 1행 응답은 제공하지 않습니다. 외부에서 sent_count/open_count/purchase_count/revenue/cost를 합산하시면 됩니다.

Q. 시나리오·인앱 메시지 성과도 같은 API로 받을 수 있나요? A. 본 API는 캠페인 전용입니다. 시나리오·인앱 메시지 성과 API는 별도로 제공될 예정입니다.

Q. 유저별 raw 이벤트(누가 언제 오픈/전환했는지)도 받을 수 있나요? A. 본 API는 집계 수치만 제공합니다. 유저별 raw 이벤트는 별도 API로 제공 예정입니다.



추가 문의는 블럭스 기술지원팀에 연락주세요.