API 개발 문서 개요

Amplitude 서버 연동 API는 목적에 따라 크게 두 가지로 구분됩니다. 본 문서는 데이터 업로드와 사용자 데이터 삭제(개인정보) 영역을 다룹니다.

공식 문서: HTTP V2 API · User Privacy API

개요 · 엔드포인트

서버·백엔드에서 SDK 없이 이벤트를 전송할 때 사용합니다. Browser SDK 2도 동일한 V2 스펙을 사용합니다.

SDK와 API를 함께 쓸 때 세션을 맞추는 방법은 WEB 가이드 · API 연동 간 세션 유지 방안을 참고하세요.

POST https://api2.amplitude.com/2/httpapi

요청 형식

• Header: Content-Type: application/json
• Body: api_key(필수), events(필수, 배열), options(선택)

이벤트 필수 조건

• event_type — 필수 (이벤트명)
• user_id 또는 device_id — 둘 중 하나 필수 (기본 최소 5자)
• time — 밀리초(epoch). 생략 시 서버 수신 시각 사용
• 문자열 값 — 최대 1024자

요청 예시 (Event)

curl -X POST https://api2.amplitude.com/2/httpapi \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "events": [{
      "user_id": "user_12345",
      "device_id": "device_abcdef",
      "event_type": "purchase_completed",
      "time": 1396381378123,
      "insert_id": "550e8400-e29b-41d4-a716-446655440000",
      "event_properties": {
        "product_id": "SKU-001",
        "price": 29900
      },
      "user_properties": {
        "plan": "premium"
      },
      "session_id": 1716245958483
    }]
  }'

요청 예시 (User Property)

event_type을 $identify로 보내고, user_properties에 연산자를 사용합니다.

{
  "api_key": "YOUR_API_KEY",
  "events": [{
    "user_id": "user_12345",
    "event_type": "$identify",
    "user_properties": {
      "$set": { "membership": "gold" },
      "$setOnce": { "signup_date": "2024-01-15" },
      "$add": { "login_count": 1 }
    }
  }]
}

옵션 — ID 최소 길이 override

{
  "api_key": "YOUR_API_KEY",
  "options": { "min_id_length": 1 },
  "events": [ ... ]
}

응답 코드 요약

성공 응답 예시

{
  "code": 200,
  "events_ingested": 1,
  "payload_size_bytes": 512,
  "server_upload_time": 1396381378123
}

개요 · 인증 · 리전

User Privacy API는 특정 사용자의 Amplitude 데이터 삭제 Job을 등록·조회·취소합니다. 삭제 요청 후 실제 삭제는 배치 Job으로 처리되며, 완료까지 일정 기간이 소요될 수 있습니다.

공식 문서: User Privacy API

Base URL (리전)

주의: REST 요청은 위 Base URL을 사용합니다. https://analytics.amplitude.com은 웹 대시보드(브라우저 UI)용이므로 API 호출에 사용하지 마세요.

인증 (HTTP V2와 다름)

• Basic Authentication: API_KEY:SECRET_KEY
• cURL 예: -u YOUR_API_KEY:YOUR_SECRET_KEY
• HTTP V2처럼 JSON Body에 api_key만 넣는 방식이 아닙니다.

주요 엔드포인트

• POST /api/2/deletions/users — 삭제 대상 사용자 등록
• GET /api/2/deletions/users?start_day=&end_day= — 삭제 Job 목록 조회
• DELETE /api/2/deletions/users/{amplitude_id}/{job_start_day} — Job에서 특정 사용자 제외(취소)

주의사항

• 기본적으로 요청한 API Key가 속한 프로젝트만 삭제됩니다. 조직 전체 삭제는 delete_from_org: true 필요.
• 삭제 요청 시 Amplitude가 계정 관리자에게 이메일로 알립니다.
• Job 실행 시점까지의 이벤트·User Property가 삭제 대상입니다.
• 삭제 후에도 동일 ID로 새 이벤트가 수집될 수 있습니다. API만으로 미래 추적을 막지 않습니다 → SDK setOptOut() 등 별도 처리 필요.
• 삭제된 사용자의 후속 이벤트는 신규 사용자로 집계될 수 있습니다.
• GDPR 기준 요청 접수 후 최대 30일 이내 처리. 대용량(월 10억+ 이벤트)은 스케줄 빈도 조정 가능.
• Job 예정일 3일 전까지는 배치에서 사용자 제외(취소) 가능. 이후 submitted 상태에서는 중단 불가.
• Data Warehouse(CDC) 등 외부 적재 소스에 데이터가 남아 있으면 재동기화 시 재유입될 수 있습니다 → 원천 DB 삭제 병행 권장.

제한 · Rate Limit

• POST /api/2/deletions/users: 초당 1회 요청
• 요청 1회당 최대 100명 (user_ids + amplitude_ids 합산)
• 프로젝트당 동시 실행 Job: 최대 8개
• 요청당 100명 × 초당 1회 = 이론상 초당 100명 등록 가능

사용자 삭제 요청 (POST)

POST https://amplitude.com/api/2/deletions/users

Body(JSON)에 삭제할 user_ids 및/또는 amplitude_ids를 지정합니다. (최대 100명)

Body 파라미터

요청 예시 — 단일 프로젝트

curl -X POST 'https://amplitude.com/api/2/deletions/users' \
  -H 'Content-Type: application/json' \
  -u 'YOUR_API_KEY:YOUR_SECRET_KEY' \
  -d '{
    "user_ids": ["user_12345"],
    "amplitude_ids": [987654321],
    "requester": "privacy-team@company.com",
    "ignore_invalid_id": false,
    "delete_from_org": false
  }'

요청 예시 — 조직 전체 프로젝트

curl -X POST 'https://amplitude.com/api/2/deletions/users' \
  -H 'Content-Type: application/json' \
  -u 'YOUR_API_KEY:YOUR_SECRET_KEY' \
  -d '{
    "user_ids": ["user_12345"],
    "requester": "dpo@company.com",
    "delete_from_org": true
  }'

응답 예시

{
  "day": "2026-05-20",
  "status": "staging",
  "amplitude_ids": [
    {
      "amplitude_id": 987654321,
      "user_id": "user_12345",
      "requester": "privacy-team@company.com",
      "requested_on_day": "2026-05-19"
    }
  ],
  "invalid_ids": []
}

status: staging(수정 가능) → submitted(실행 예정, 수정 불가) → done(완료)

삭제 Job 조회 (GET)

GET https://amplitude.com/api/2/deletions/users?start_day=YYYY-MM-DD&end_day=YYYY-MM-DD

요청일 기준 요청일 + 30일 범위를 조회하는 것을 권장합니다. 최대 조회 범위는 6개월입니다.

Query 파라미터

• start_day (필수) — YYYY-MM-DD
• end_day (필수) — YYYY-MM-DD

요청 예시

curl -X GET 'https://amplitude.com/api/2/deletions/users?start_day=2026-05-19&end_day=2026-06-18' \
  -H 'Accept: application/json' \
  -u 'YOUR_API_KEY:YOUR_SECRET_KEY'

응답 예시

[
  {
    "day": "2026-05-20",
    "status": "staging",
    "app": 123456,
    "amplitude_ids": [
      {
        "amplitude_id": 987654321,
        "requester": "privacy-team@company.com",
        "requested_on_day": "2026-05-19"
      }
    ],
    "active_scrub_done_date": null
  }
]

Job에서 사용자 제외 (DELETE)

예정 Job(staging)에서 특정 Amplitude ID를 제거합니다. Job 시작 3일 전까지 가능합니다.

DELETE https://amplitude.com/api/2/deletions/users/{AMPLITUDE_ID}/{JOB_START_DAY}

Path 변수

• AMPLITUDE_ID — Job에서 제외할 Amplitude ID
• JOB_START_DAY — Job 예정일 (YYYY-MM-DD)

요청 예시

curl -X DELETE \
  'https://amplitude.com/api/2/deletions/users/987654321/2026-05-20' \
  -H 'Content-Type: application/json' \
  -u 'YOUR_API_KEY:YOUR_SECRET_KEY'

응답 예시

{
  "amplitude_id": 987654321,
  "requested_on_day": "2026-05-19",
  "requester": "privacy-team@company.com"
}

응답 코드 (User Privacy API)