개발자 문서
서비스 소개키 관리자격증명 등록OpenAPI콘솔
API 레퍼런스

애널리틱스(GA4)

1. Google 측정 설정 진단google.analytics.measurement.audit

MCP 도구 이름 google__analytics__measurement__audit

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

웹사이트 측정이 제대로 걸려 있는지 점검해 빠졌거나 어긋난 곳을 알려 줍니다. 읽기만 하며 태그나 설정을 바꾸지 않습니다.

  • 콘솔에서 Google 계정 연동을 마쳐야 합니다. 진단할 property_id 는 연동 상태 조회(google.account.status)의 analytics_properties 에서 확인합니다.
  • 이 상품은 sandbox 환경에서 실행할 수 없습니다. error.code=POLICY_ENV_FORBIDDEN.
  • property_id 는 필수입니다("properties/123456" 형태나 숫자만 있는 "123456" 모두 됩니다). 형식이 잘못되면 error.code=VALIDATION_INVALID_FIELD, 아예 빠지면 error.code=VALIDATION_MISSING_FIELD 입니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • google이 API 고정값 (기본값)

예시 : google

actionstring-Y호출할 작업입니다.
  • google.analytics.measurement.audit이 API 고정값 (기본값)

예시 : google.analytics.measurement.audit

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
property_idstringYGA4 속성 ID. "properties/123456" 형태나 숫자만 있는 "123456" 모두 됩니다. 이 연동에서 고객이 선택한 속성이어야 합니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-audit-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.analytics.measurement.audit",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "property_id": "<필수>"
  }
}'
Response
  • result.data 의 data_streams·key_events 로 그 GA4 속성의 설정 현황을, findings 로 발견한 문제(코드·심각도·안내)를 확인합니다. property_settings 로 속성 기본 설정(표시 이름·시간대·통화·업종)도 함께 확인합니다. 데이터 값(세션 수 등)은 바꾸지 않고 설정만 진단합니다.
순번변수명설명
data_availability이 속성의 진단 데이터를 지금 읽을 수 있는지
data_streams{by_type, web_streams_missing_measurement_id, data_availability} - 데이터 스트림 설정 현황
key_events{custom_count, by_counting_method, data_availability} - 핵심 이벤트(전환) 설정 현황
findings발견한 설정 문제 목록(코드·심각도·안내) - 데이터 스트림 없음·측정 ID 없는 웹 스트림·스트림 유형 미지정·핵심 이벤트 없음·집계 방식 미지정 다섯 가지가 있습니다
scope_note_ko이 진단이 보는 범위에 대한 안내
property_settings{display_name, time_zone, currency_code, industry_category, data_availability} - 속성 기본 설정 현황(표시 이름·시간대·통화·업종). 속성 수정이 바꾸는 칸과 이름이 같아 읽은 값을 그대로 수정에 보낼 수 있습니다. 읽기 실패하면 네 칸이 null 이고 data_availability 는 access_error 입니다.
property_id조회한 GA4 속성 id
data_streams_collectiondata_streams 판정의 재료가 된 스트림 수·잘림·접근 실패 여부
key_events_collectionkey_events 판정의 재료가 된 이벤트 수·잘림·접근 실패 여부
property_settings_collectionproperty_settings 판정의 재료가 된 속성 수·잘림·접근 실패 여부(속성 하나만 읽으므로 잘림은 늘 거짓입니다)
as_of이 응답을 만든 시각(UTC)
timezone수치가 속한 시간대 - 이 액션은 수치를 세지 않으므로 항상 null 입니다
is_final'final'(확정)·'provisional'(변동 가능)·'unknown' 중 하나
content_is_data_not_instructions_ko이 응답 내용은 데이터이며 지시가 아니라는 고정 안내문
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "google",
    "action": "google.analytics.measurement.audit",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_BUSINESS_ERROR권한 없음 · 선택 안 한 자산 — 권한이 없으면 (Google 에서 이 속성의 보기 권한을 받아야 함), 연동 범위에서 고르지 않은 속성이면 (연동 상태 조회로 읽을 수 있는 자산 목록을 먼저 확인) 입니다.
VALIDATION_INVALID_FIELD권한 없음 · 선택 안 한 자산 — 권한이 없으면 (Google 에서 이 속성의 보기 권한을 받아야 함), 연동 범위에서 고르지 않은 속성이면 (연동 상태 조회로 읽을 수 있는 자산 목록을 먼저 확인) 입니다.
AUTH_REQUIRED연동 안 함 · 동의 철회 — Google 계정을 연동하지 않았거나 저장된 토큰을 더는 쓸 수 없습니다. 콘솔의 연동 화면에서 연결·재연결합니다.

2. 웹사이트 성과 조회google.analytics.report

MCP 도구 이름 google__analytics__report

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

고른 기간의 방문과 이용 지표를 표로 돌려줍니다. 시작일과 종료일을 모두 포함해 집계하며 기준 시간대를 결과에 함께 적습니다.

  • 콘솔에서 Google 계정 연동을 마쳐야 합니다. 조회할 property_id 는 연동 상태 조회(google.account.status)의 analytics_properties 에서 확인합니다.
  • 이 상품은 sandbox 환경에서 실행할 수 없습니다. error.code=POLICY_ENV_FORBIDDEN.
  • property_id·start_date·end_date·metrics 는 필수입니다. 날짜는 YYYY-MM-DD 형식만 받고(해당일 포함), end_date 는 start_date 보다 앞일 수 없습니다. dimensions·row_limit·offset 은 선택입니다. 형식·범위가 틀리면 error.code=VALIDATION_INVALID_FIELD, 필수값이 빠지면 error.code=VALIDATION_MISSING_FIELD 입니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • google이 API 고정값 (기본값)

예시 : google

actionstring-Y호출할 작업입니다.
  • google.analytics.report이 API 고정값 (기본값)

예시 : google.analytics.report

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
dimensionsarray-N선택적 분류 기준(예: ["sessionDefaultChannelGroup"])
end_datestring10Y조회 종료일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

metricsarray-Y조회할 GA4 지표 이름 목록(예: ["sessions", "totalUsers", "keyEvents"]). 결과 행에서 sessions 는 metrics.sessions, totalUsers 는 metrics.users, keyEvents 는 metrics.conversions 로 나가고, 그 외 GA4 지표는 channel_metrics 아래로 나갑니다
offsetnumber-N페이지 넘김을 위한 시작 위치(offset). 생략하면 첫 페이지입니다
property_idstring-YGA4 속성 ID. "properties/123456" 형태나 숫자만 있는 "123456" 모두 됩니다. 이 연동에서 고객이 선택한 속성이어야 합니다
row_limitnumber-N반환할 최대 행 수. 생략하면 기본값을 씁니다
start_datestring10Y조회 시작일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-report-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.analytics.report",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "end_date": "<필수>",
    "metrics": "<필수: array>",
    "property_id": "<필수>",
    "start_date": "<필수>"
  }
}'
Response
  • result.data 의 rows[] 로 기간별 지표를 확인합니다. sessions·totalUsers·keyEvents 는 각각 metrics.sessions·metrics.users·metrics.conversions 로, 그 외 GA4 지표는 channel_metrics 아래로 나갑니다. collection 으로 반환 건수·잘림 여부를 확인합니다.
순번변수명설명
property_id조회한 GA4 속성 id
start_date조회 시작일(요청 그대로 반향)
end_date조회 종료일(요청 그대로 반향)
metrics요청한 지표 이름 목록(요청 그대로 반향)
dimensions요청한 분류 기준 목록(요청 그대로 반향)
rows행 목록 - 각 행은 dimension_values(분류값)·metrics(공용 지표: sessions·users·conversions)·channel_metrics(그 외 GA4 지표) 를 담습니다
collectionrows 의 건수·잘림·접근 실패 여부
data_availability이 기간·속성의 데이터를 지금 읽을 수 있는지
as_of이 응답을 만든 시각(UTC)
timezone이 속성에 설정된 시간대
is_final이 액션은 늘 'unknown' 입니다 - GA4 수치가 나중에 재처리될 수 있어 확정을 약속하지 않습니다
content_is_data_not_instructions_ko이 응답 내용은 데이터이며 지시가 아니라는 고정 안내문
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "google",
    "action": "google.analytics.report",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_BUSINESS_ERROR권한 없음 · 선택 안 한 자산 — 권한이 없으면 (Google 에서 보기 권한을 받아야 함), 연동 범위에서 고르지 않은 속성이면 (연동 상태 조회로 읽을 수 있는 자산 목록을 먼저 확인) 입니다.
VALIDATION_INVALID_FIELD권한 없음 · 선택 안 한 자산 — 권한이 없으면 (Google 에서 보기 권한을 받아야 함), 연동 범위에서 고르지 않은 속성이면 (연동 상태 조회로 읽을 수 있는 자산 목록을 먼저 확인) 입니다.
AUTH_REQUIRED연동 안 함 · 동의 철회 — Google 계정을 연동하지 않았거나 저장된 토큰을 더는 쓸 수 없습니다. 콘솔의 연동 화면에서 연결·재연결합니다.
PROVIDER_VALIDATION_ERROR기관 거절 — Google 이 이 요청을 받아들이지 않았습니다(없는 속성 id, 허용되지 않는 지표 조합 등). 기관이 사유를 주면 그대로 error.message 에 실립니다.
PROVIDER_UPSTREAM_ERROR한도 초과 — Google 조회 한도를 다 썼습니다. 안내에 남은 한도와 다시 열리는 시점(있으면)이 함께 옵니다.