Mixpanel API 쿼리

Mixpanel Query API는 웹 앱의 보고서에서 보는 것과 동일한, 계산·포맷된 결과를 코드로 가져올 수 있게 해주는 분석 쿼리 API예요. 이벤트 필터링·분해, 유저 프로필 조회, 유저의 활동/이벤트 스트림, 코호트 조회 등 원하는 분석 데이터를 자동화된 방식으로 꺼내 쓸 수 있어요. 쿼리 엔드포인트는 Mixpanel에서 사용자 정보를 내보낼 때 출발점이 되며, 인증은 서비스 계정이나 프로젝트 시크릿을 통해 처리해요.

출처: Mixpanel Query API Overview

본문

Query API는 웹 앱의 보고서에서 볼 수 있는 것과 똑같이 계산되고 포맷된 결과를 얻을 수 있게 해줘요. 유저 정보를 Mixpanel에서 내보낼 때는 쿼리 엔드포인트부터 시작하세요. 이는 /engage 엔드포인트를 통해 처리되며, 이벤트 데이터 내보내기에 대한 내용은 Export 섹션을 참조하면 돼요.

Mixpanel Query API 엔드포인트가 할 수 있는 일은 이렇게 다양해요.

이벤트 필터링 / 분해(breakdown): 이벤트를 속성 기준으로 자르고 거르기
유저 프로필 반환: 조건에 맞는 유저(또는 그룹) 프로필 조회
활동/이벤트 스트림 반환: 유저의 최근 이벤트 내역
코호트 반환: 특정 코호트에 속한 유저 목록
그리고 그 이상!

주요 쿼리 엔드포인트

즉시 사용 가능한 쿼리 엔드포인트는 크게 네 가지로 나뉘어요.

엔드포인트	담당 보고서	설명
`/segmentation`	Segmentation	이벤트 데이터를 속성으로 분해·필터링해 조회
`/funnels`	Funnels	퍼널(단계별 전환) 보고서 데이터 조회
`/retention`	Retention	코호트(유지율) 분석 조회
`/engage`	Engage	유저/그룹 프로필 데이터 조회

이 이벤트·퍼널·리텐션 쿼리는 모두 https://{regionAndDomain}.com/api/query 서버를 기준으로 동작해요. 기본(미국) 서버는 mixpanel, EU 데이터 거주지역은 eu.mixpanel, 인도는 in.mixpanel을 사용해요.

이벤트 조회 (Segmentation)

이벤트 하나를 골라 속성으로 분해·필터링한 데이터를 가져와요. 기본 서버를 기준으로 한 예시는 다음과 같아요.

curl "https://mixpanel.com/api/2.0/segmentation" \
  -u "$YOUR_API_SECRET" \
  -d event="Signed up" \
  -d from_date="2024-01-01" \
  -d to_date="2024-01-07" \
  -d where='"profile"."country" == "KR"'

파라미터를 정리하면 이래요.

event: 데이터를 가져올 단일 이벤트 이름 (배열이 아니라 단일 값)
from_date / to_date: 조회할 기간 (yyyy-mm-dd 형식, 시작·종료일 포함)
unit: minute, hour, day, month 중 하나로, 분해할 값의 버킷 크기를 정해요. 기본값은 day
type: general(반복 포함 총계), unique(고유 이벤트 수), average(평균 개수). 기본값은 general
on: 이벤트를 분해할 속성 표현식
where: 이벤트를 필터링할 표현식
limit: 상위 속성값 개수. 기본 60, 최대 10,000
format: csv로 설정하면 CSV 응답을 받을 수 있어요

퍼널 조회 (Funnels)

퍼널 단계별 전환 데이터를 가져와요. 저장된 퍼널의 funnel_id를 기준으로 조회해요.

curl "https://mixpanel.com/api/2.0/funnels" \
  -u "$YOUR_API_SECRET" \
  -d funnel_id=12345 \
  -d from_date="2024-01-01" \
  -d to_date="2024-01-07"

응답은 각 날짜별 steps 배열에 단계별 count(전환 수), step_conv_ratio(직전 단계 대비 전환율), overall_conv_ratio(퍼널 시작 대비 전환율) 등을 담고 있어요. length 파라미터로 유저가 첫 단계를 트리거한 시점부터 퍼널을 완료할 수 있는 단위 개수(day/hour/minute/second)를 제한할 수 있고, 90일을 넘길 수 없어요.

리텐션 조회 (Retention)

코호트(유지율) 분석을 가져와요. interval도 unit도 지정하지 않으면 interval은 1일이 되어, 각 유저가 각 구간에서 이벤트를 수행할 시간은 24시간이 돼요.

born_event가 event integration이고 event가 viewed report일 때의 응답 예시를 보면 이래요.

{
  "2012-01-01": {
    "counts": [2, 1, 2],
    "first": 2
  },
  "2012-01-02": {
    "counts": [9, 7, 6],
    "first": 10
  },
  "2012-01-03": {
    "counts": [9, 6, 4],
    "first": 10
  }
}

이 결과는 2012-01-02에 first 필드가 가리키듯 10명의 유저가 born_event("event integration")를 수행했음을 뜻해요. 그중 9명은 born_event 후 24시간 안에("0th" 구간), 7명은 24~48시간 사이(구간 1)에 event를 수행했어요. 리텐션은 퍼널이 아니므로 이 7명이 반드시 9명의 부분집합일 필요는 없어요.

유저 프로필 조회 (Engage)

조건을 충족하는 유저(또는 그룹) 프로필 목록을 반환해요. 응답은 요청당 많아야 page_size개 레코드를 반환하므로, 페이지네이션으로 전체를 순회할 수 있어요.

// Get the first page of data associated with our selector expression
this_page = query_api(where=YOUR_SELECTOR_EXPRESSION)
do_something_with_response(this_page)

// If we get fewer records than the page_size returned with our results,
// then there are no more records to get. Otherwise, keep querying for additional pages.
while (length of this_page.results) >= this_page.page_size:
    next_page_number = this_page.page + 1
    this_page = query_api(where=YOUR_SELECTOR_EXPRESSION, session_id=this_page.session_id, page=next_page_number)
    do_something_with_response(this_page)

사용량 제한

Query API는 시간당 60회 쿼리, 최대 5개 동시 쿼리라는 할당량이 있어요. 대량 조회를 할 때는 이 한도를 감안해 페이지네이션과 요청 간격을 설계해야 해요.

더 알아보기 (Learn more)

공식 문서