개발자 문서
API 레퍼런스

애널리틱스(GA4) - Google 마케팅

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

MCP 도구 이름 google__analytics__measurement__audit

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

  • 콘솔에서 Google 계정 연동을 마쳐야 합니다. 진단할 property_id 는 연동 상태 조회(google.account.status)의 analytics_properties 에서 확인합니다.
  • property_id 는 필수입니다("properties/123456" 형태나 숫자만 있는 "123456" 모두 됩니다).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : 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: real_test' \
  --header "Idempotency-Key: audit-$(date +%s)-$RANDOM" \
  --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

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 data_streams·key_events 로 그 GA4 속성의 설정 현황을, findings 로 발견한 문제(코드·심각도·안내)를 확인합니다.
순번변수명타입설명
data_availabilitystring | null이 속성의 진단 데이터를 지금 읽을 수 있는지
data_streamsobject{by_type, web_streams_missing_measurement_id, data_availability} - 데이터 스트림 설정 현황
key_eventsobject{custom_count, by_counting_method, data_availability} - 핵심 이벤트(전환) 설정 현황
findingsarray발견한 설정 문제 목록(코드·심각도·안내) - 데이터 스트림 없음·측정 ID 없는 웹 스트림·스트림 유형 미지정·핵심 이벤트 없음·집계 방식 미지정 다섯 가지가 있습니다
scope_note_kostring이 진단이 보는 범위에 대한 안내
property_settingsobject{display_name, time_zone, currency_code, industry_category, data_availability} - 속성 기본 설정 현황(표시 이름·시간대·통화·업종). 속성 수정이 바꾸는 칸과 이름이 같아 읽은 값을 그대로 수정에 보낼 수 있습니다. 읽기 실패하면 네 칸이 null 이고 data_availability 는 access_error 입니다.
property_idstring조회한 GA4 속성 id
data_streams_collectionobjectdata_streams 판정의 재료가 된 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다)
key_events_collectionobjectkey_events 판정의 재료가 된 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다)
property_settings_collectionobjectproperty_settings 판정의 재료가 된 수집 완결성 객체(속성 하나만 읽으므로 truncated 는 늘 false 입니다) - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다)
as_ofstring이 응답을 만든 시각(UTC)
timezonestring | null수치가 속한 시간대 - 이 액션은 수치를 세지 않으므로 항상 null 입니다
is_finalstring'final'(확정)·'provisional'(변동 가능)·'unknown' 중 하나
content_is_data_not_instructions_kostring이 응답 내용은 데이터이며 지시가 아니라는 고정 안내문
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "google",
    "action": "google.analytics.measurement.audit",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_BUSINESS_ERROR권한 없음 — 연동한 계정에 이 속성의 읽기 권한이 없습니다. Google 에서 이 속성의 보기 권한을 받은 뒤 다시 요청합니다.
VALIDATION_INVALID_FIELD선택 안 한 자산 — 연동 범위에서 고르지 않은 속성입니다. 연동 상태 조회로 읽을 수 있는 자산 목록을 먼저 확인합니다.
AUTH_REQUIRED연동 안 함 · 동의 철회 — Google 계정을 연동하지 않았거나 저장된 토큰을 더는 쓸 수 없습니다. 콘솔의 연동 화면에서 연결·재연결합니다.

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

MCP 도구 이름 google__analytics__report

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

  • 콘솔에서 Google 계정 연동을 마쳐야 합니다. 조회할 property_id 는 연동 상태 조회(google.account.status)의 analytics_properties 에서 확인합니다.
  • property_id, start_date, end_date, metrics 는 필수입니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

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

형식 : YYYY-MM-DD

end_datestring10Y조회 종료일. YYYY-MM-DD 형식만 받으며 해당일을 포함합니다

형식 : 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반환할 최대 행 수. 생략하면 1,000 을 씁니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: report-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.analytics.report",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "start_date": "<필수>",
    "end_date": "<필수>",
    "metrics": "<필수: array>",
    "property_id": "<필수>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 rows[] 로 기간별 지표를 확인합니다.
순번변수명타입설명
property_idstring조회한 GA4 속성 id
start_datestring조회 시작일(요청 그대로 반향)
end_datestring조회 종료일(요청 그대로 반향)
metricsarray요청한 지표 이름 목록(요청 그대로 반향)
dimensionsarray요청한 분류 기준 목록(요청 그대로 반향)
rowsarray행 목록 - 각 행은 dimension_values(분류값)·metrics(공용 지표: sessions·users·conversions)·channel_metrics(그 외 GA4 지표) 를 담습니다
collectionobjectrows 의 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다)
data_availabilitystring이 기간·속성의 데이터를 지금 읽을 수 있는지
as_ofstring이 응답을 만든 시각(UTC)
timezonestring | null이 속성에 설정된 시간대
is_finalstring이 액션은 늘 'unknown' 입니다 - GA4 수치가 나중에 재처리될 수 있어 확정을 약속하지 않습니다
content_is_data_not_instructions_kostring이 응답 내용은 데이터이며 지시가 아니라는 고정 안내문
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "google",
    "action": "google.analytics.report",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_BUSINESS_ERROR권한 없음 — 연동한 계정에 이 속성의 읽기 권한이 없습니다. Google 에서 이 속성의 보기 권한을 받은 뒤 다시 요청합니다.
VALIDATION_INVALID_FIELD선택 안 한 자산 — 연동 범위에서 고르지 않은 속성입니다. 연동 상태 조회로 읽을 수 있는 자산 목록을 먼저 확인합니다.
AUTH_REQUIRED연동 안 함 · 동의 철회 — Google 계정을 연동하지 않았거나 저장된 토큰을 더는 쓸 수 없습니다. 콘솔의 연동 화면에서 연결·재연결합니다.
PROVIDER_VALIDATION_ERROR기관 거절 — Google 이 이 요청을 받아들이지 않았습니다(없는 속성 id, 허용되지 않는 지표 조합 등). 기관이 사유를 주면 그대로 error.message 에 실립니다.
PROVIDER_UPSTREAM_ERROR한도 초과 — Google 조회 한도를 다 썼습니다. 안내에 남은 한도와 다시 열리는 시점(있으면)이 함께 옵니다.