본문으로 건너뛰기

캠페인 성과 조회하기

특정 기간 동안 발송된 캠페인의 성과 집계 수치를 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 또는 YYYY-MM-DD)(필수) 조회 시작 일시 (inclusive)
task_tostring (ISO 8601 또는 YYYY-MM-DD)(필수) 조회 종료 일시 (exclusive)
campaign_schedule_typestring(선택) 캠페인 종류 필터. once, recurring, api_trigger 중 하나. 미지정 시 모든 종류를 합쳐서 반환합니다.
  • task_from과 task_to 사이의 기간은 최대 180일까지 지원됩니다.
  • task가 task_from <= scheduled_at < task_to 범위에 들어가는 캠페인이 응답에 포함됩니다.

일시는 timezone offset(Z 또는 ±HH:MM)을 붙여 보내는 것을 권장합니다. offset이 없는 일시(2026-05-01T00:00:00)는 한국 시간(KST) 으로 해석됩니다. 날짜만(YYYY-MM-DD) 보내면 task_from은 그날 00:00 KST, task_to는 다음 날 00:00 KST로 해석되어 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,
          "click_target_counts": [
            { "click_target": "button_1", "count": 240, "user_count": 232 },
            { "click_target": "carousel_1_button_1", "count": 55, "user_count": 54 },
            { "click_target": "carousel_1_coupon", "count": 25, "user_count": 25 }
          ],
          "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클릭 수
click_target_countsarray오픈 수를 눌린 위치별로 나눈 집계. 아래 버튼별 클릭 수 참고. 집계할 이벤트가 없으면 필드가 빠집니다
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 등)가 채널에 따라 함께 반환될 수 있습니다.

버튼별 클릭 수​

click_target_counts는 회차의 오픈 수(open_count)를 메시지 안에서 눌린 위치별로 나눈 집계입니다. 어떤 버튼이 실제로 눌렸는지 회차 단위로 바로 확인할 수 있습니다.

필드타입설명
click_targetstring눌린 위치. 아래 채널별 값 참고
countnumber해당 위치의 클릭 수 (중복 O)
user_countnumber해당 위치를 누른 회원 수 (중복 X)

배열은 click_target 사전순으로 정렬해 반환하므로, 시트에 일 단위로 쌓을 때 열 순서를 고정할 수 있습니다.

채널별 click_target 값​

채널값의 예버튼 구분
카카오 브랜드메시지, 친구톡button_1, image, carousel_1_button_1, carousel_1_coupon일반 메시지는 몇 번째 버튼인지, 캐러셀은 몇 번째 카드의 버튼·쿠폰인지까지 구분됩니다
SMS, RCSbody_1, button_1본문 링크와 버튼이 구분됩니다
알림톡alimtalk버튼이 구분되지 않습니다. 알림톡은 눌린 위치를 기록하지 않아 모든 클릭이 한 값으로 모입니다

주의​

  • count의 합은 open_count보다 작을 수 있습니다. 눌린 위치가 기록되지 않은 이벤트는 특정 버튼의 클릭 수로 읽히지 않도록 이 집계에서 제외하기 때문입니다. 전체 오픈 수는 open_count를 쓰세요.
  • 집계할 이벤트가 없으면 필드 자체가 빠집니다. 오픈이 0인 회차, 웹훅처럼 클릭을 수집하지 않는 채널의 회차가 여기에 해당합니다. 빈 배열이 아니라 키가 없으므로 undefined 처리를 해두세요.
  • 이 집계가 도입되기 전에 전환 기한이 끝난 회차에는 필드가 없습니다. 클릭이 없었다는 뜻이 아니라 집계를 하지 않은 회차라는 뜻이므로, 0으로 읽지 마세요. 그 시점의 버튼별 클릭은 데이터 내보내기 API의 캠페인 원본 이벤트 CSV에서 click_target으로 확인할 수 있습니다.
  • 대체 발송 몫은 원본과 합산해 셉니다. 위 click_target_counts는 원본 발송분과 대체 발송분을 더한 값이고, fallback_message 안 click_target_counts가 그중 대체 발송 몫입니다. 원본 발송분만 필요하면 두 값을 빼서 구하세요. open_count를 비롯한 다른 집계 수치도 같은 규칙을 따릅니다.
  • 유저별 원본 이벤트가 필요하면 데이터 내보내기 API로 캠페인 원본 이벤트 CSV를 받으세요. CSV의 internal_event_properties 안 click_target이 같은 값입니다.

제한 사항​

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

상태 코드​

코드설명
200 OK정상 응답
400 Bad Request필수 query 파라미터 누락, 형식 오류, 또는 기간 180일 초과
400 Bad Request인증 실패 (secret key 오류, 또는 다른 application의 키 사용) — errorCode: UnAuthorized
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. 각 task의 click_target_counts가 눌린 위치별 클릭 수입니다. 브랜드메시지·친구톡은 버튼과 캐러셀 카드까지 구분되고, 알림톡은 눌린 위치를 기록하지 않아 구분되지 않습니다. 버튼별 클릭 수를 참고하세요.

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

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

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



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