이 페이지에서

행동 코호트 API

지역

기본 URL은 프로젝트의 데이터 상주 위치에 따라 달라집니다. 이 페이지의 모든 예제에서 프로젝트가 Amplitude의 EU 데이터 센터를 사용하지 않는 한 기본 URL을 사용하십시오. 이 경우 이 표의 EU 기본 URL을 사용하십시오.

요청은 https://amplitude.com(기본값) 또는 https://analytics.eu.amplitude.com (EU)로 이동합니다. https://analytics.amplitude.com호스트 이름은 분석 웹 앱(브라우저 UI)입니다. REST 요청에는 analytics.amplitude.com이 표에 나와 있는 호스트를 사용하십시오.

데이터 상주기본 URL
기본값https://amplitude.com
EUhttps://analytics.eu.amplitude.com

제한 사항 및 고려 사항

  • 그로쓰 및 엔터프라이즈 플랜의 경우 행동 코호트 다운로드 API는 매월 500건의 요청으로 제한됩니다. 각 코호트 요청 하나는 이 한도에 포함됩니다. Get usage 엔드포인트를 사용하여 현재 사용량을 확인하세요.
  • Amplitude는 최대 200만 명의 코호트 규모를 지원합니다. 더 큰 코호트의 경우 다음 중 하나를 사용하십시오.
    • Amazon Kinesis에 대한 코호트 동기화 생성
    • 웹후크를 사용하여 사용자 지정 대상으로 코호트 동기화를 생성하세요
    • 프로필 API에 대한 코호트 동기화 생성
  • 동시 실행률 제한은 코호트 다운로드 및 대시보드 REST API 전체에서 5개의 요청입니다.
  • 코호트 다운로드는 비동기 API를 사용합니다. 코호트를 얻으려면 다음 세 단계를 완료하십시오.
    1. 단일 코호트를 요청하십시오.
    2. 코호트 상태를 조사합니다.
    3. 파일을 다운로드합니다.
  • 코호트 다운로드는 앱의 단일 코호트 요청을 10분당 60건의 요청, 4건의 병렬 요청으로 제한합니다.
  • Amplitude는 단일 요청을 100,000개의 식별자로 제한합니다.

모든 코호트 확인

앱에 대해 검색 가능한 모든 코호트를 가져옵니다. 단일 코호트를 얻으려면 응답에 반환된 각 코호트에 대해 id을 사용하십시오.

curl --location --request GET 'https://amplitude.com/api/3/cohorts' \
-u '{api_key}:{secret_key}'

쿼리 매개 변수

이름설명
includeSyncInfo선택 사항입니다. 부울입니다. 응답에 코호트 동기화 메타데이터를 포함하도록 true설정합니다. 응답에는 일회성 데이터 동기화 및 비활성화된 데이터 동기화가 제외됩니다.

응답

응답은 다음 스키마를 가진 JSON 객체입니다.

json
{
    "cohorts": [
        { COHORT_OBJECT },
        ...
        { COHORT_OBJECT },
    ]
}

반환되는 각 COHORT_OBJECT에는 다음 스키마가 있습니다.

json
{
    "appId": integer,
    "archived": boolean, // whether cohort is archived
    "definition": { COHORT_DEFINITION }, // Amplitude internal representation of Cohort Definition
    "description": string,
    "finished": boolean, // Amplitude internal use to decide whether a training cohort has finished ML training
    "id": string,
    "name": string,
    "owners": string[],
    "viewers": string[],
    "published": boolean, // whether cohort is discoverable by other users
    "size": integer,
    "type": string, // Amplitude internal representation on different cohort types
    "lastMod": timestamp, // last modified date
    "createdAt": timestamp,
    "lastComputed": timestamp,
    "hidden": boolean, // Amplitude internal use case to hide a cohort
    "metadata": string[], // cohort created from funnel/microscope might have this
    "view_count": integer,
    "popularity": integer, // cohort created from chart might have this
    "last_viewed": timestamp,
    "chart_id": string, // cohort created from chart will have this
    "edit_id": string, // cohort created from chart will have this
    "is_predictive": boolean,
    "is_official_content": boolean,
    "location_id": string, // cohort created from chart might have this
    "shortcut_ids": string[],
    "syncMetadata": COHORT_SYNC_METADATA[]
}

각 COHORT_SYNC_METADATA에는 다음 스키마가 있습니다.

json
{
    "target": string,
    "frequency": string, // support minute (real-time), hourly, daily
    "last_successful": timestamp,
    "last_failure": timestamp,
    "params": { COHORT_SYNC_LEVEL_PARAM }
}

다음은 샘플 결과입니다.

json
"cohorts": [{
    "appId": 123456,
    "archived": false,
    "definition": {
        "version": 3,
        "countGroup": {
            "name": "User",
            "is_computed": false
        },
        "cohortType": "UNIQUES",
        "andClauses": [{
            "negated": false,
            "orClauses": [{
                "type": "event",
                "time_type": "rolling",
                "time_value": 30,
                "offset": 0,
                "interval": 1,
                "type_value": "_active",
                "operator": ">=",
                "operator_value": 1,
                "group_by": [],
                "metric": null
            }]
        }],
        "referenceFrameTimeParams": {}
    },
    "description": "test description",
    "finished": true,
    "id": "id_12345",
    "name": "Test Cohort 1",
    "owners": [
        "demo@amplitude.com"
    ],
    "viewers": [],
    "published": true,
    "size": 111,
    "type": "redshift",
    "lastMod": 1679437294,
    "createdAt": 1679437288,
    "lastComputed": 1679440233,
    "hidden": false,
    "metadata": null,
    "view_count": null,
    "popularity": null,
    "last_viewed": null,
    "chart_id": null,
    "edit_id": null,
    "is_predictive": false,
    "is_official_content": false,
    "location_id": null,
    "shortcut_ids": [],
    "syncMetadata": [{
        "target": "braze",
        "frequency": "hourly",
        "last_successful": "2023-03-21T16:09:58.848454-07:00",
        "last_failure": null,
        "params": {
            "user_id": "demo@amplitude.com"
        }
    }]
}],

한 코호트 가져오기

해당 cohort_id를 사용하여 발견 가능한 코호트를 얻습니다. 이것은 코호트 다운로드 작업의 첫 번째 단계입니다. 응답에서 반환된 request_id를 사용하여 내보내기 상태를 조회합니다.

curl --location --request GET 'https://amplitude.com/api/5/cohorts/request/id'
-u '{api_key}:{secret_key}'

경로 매개변수

이름설명
id필수입니다. 코호트 ID.

쿼리 매개 변수

이름설명
props선택 사항입니다. 정수입니다. 응답 객체에 사용자 속성을 포함하도록 1설정합니다. 요청이 계속 시간 초과되는 경우 0로 설정하거나 설정 해제합니다.
propKeys선택 사항입니다. string[]. 응답에 포함할 하나 이상의 사용자 속성입니다. 필요한 propKeys만큼 매개변수를 추가합니다. 정의되지 않고 props=1인 경우, 응답 객체는 사용 가능한 모든 사용자 속성을 반환합니다.

응답

개별 코호트 요청은 다음 JSON 객체와 함께 202 응답 코드를 반환합니다.

json
{
  "request_id": "<request_id>",
  "cohort_id": "<cohort_id>"
}

사용자 인증 또는 cohort_id가 유효하지 않은 경우 요청은 오류를 반환합니다.

요청 상태 확인

코호트에 대해 검색된 request_id를 사용하여 요청 상태를 폴링합니다. 이것은 코호트 다운로드 작업의 두 번째 단계입니다.

curl --location --request GET 'https://amplitude.com/api/5/cohorts/request-status/:request_id' \
-u '{api_key}:{secret_key}''

경로 매개변수

이름설명
request_id필수입니다. 한 코호트 가져오기 요청으로 검색된 요청 ID입니다.

응답

작업이 여전히 실행 중인 경우 요청 상태는 202 코드와 JOB INPROGRESS를 반환합니다async_status.

json
{
  "request_id": "<request_id>",
  "cohort_id": "<cohort_id>",
  "async_status": "JOB INPROGRESS"
}

작업 실행이 완료된 경우 요청 상태는 200 코드와 JOB COMPLETED를 반환합니다async_status.

json
{
  "request_id": "<request_id>",
  "cohort_id": "<cohort_id>",
  "async_status": "JOB COMPLETED"
}

코호트 다운로드

작업 실행이 완료되면 코호트를 다운로드합니다. 다음은 기본적인 요청입니다.

curl --location --request GET 'https://amplitude.com/api/5/cohorts/request/:requestId/file' \
-u '{api_key}:{secret_key}'

경로 매개변수

이름설명
request_id필수입니다. 한 코호트 가져오기 요청으로 검색된 요청 ID입니다.
  • 소규모 코호트의 경우 응답 본문에는 코호트 데이터가 포함되어 있습니다.
  • 대규모 코호트의 경우 데이터를 다운로드해야 합니다. 응답은 302 응답 코드와 함께 사전 서명된 Amazon S3 다운로드 URL로 리디렉션됩니다. 다운로드 URL은 1분 동안 유효하므로 즉시 액세스하십시오.
  • API 요청 링크(https://amplitude.com/api/5/cohorts/request/:requestId/file)는 7일 동안 유효합니다. 다음 기간동안 7일 동안 동일한 요청을 통해 새 S3 다운로드 링크를 받을 수 있습니다. 각 S3 링크는 1분 동안 유효합니다.
  • 대부분의 API 클라이언트는 S3 링크에서 데이터를 자동으로 다운로드합니다. API 클라이언트가 코호트를 자동으로 다운로드하지 않는 경우 1분 안에 수동으로 액세스할 수 있습니다.

사용량 확인

현재 월간 사용량과 행동 코호트 다운로드 API의 한도를 확인하세요.

curl --location --request GET 'https://amplitude.com/api/3/cohorts/usage' \
-u '{api_key}:{secret_key}'

응답

json
{
  "rest_download": {
    "limit": 500,
    "usage": 42,
    "resets_at": "2026-06-01T00:00:00"
  }
}

사용량은 매달 1일(UTC)에 재설정됩니다.

코호트 업로드

사용자 ID 또는 Amplitude ID 세트를 업로드하여 새로운 코호트를 생성하거나 기존 코호트를 업데이트하십시오. 다음은 자리 표시자 값을 사용하는 기본 요청 예입니다.

curl --location --request POST 'https://amplitude.com/api/3/cohorts/upload' \
--header 'Content-Type: application/json' \
-u '{api_key}:{secret_key}''
--data-raw '{
    "name": "Cohort Name",
    "app_id": amplitude_project,
    "id_type": "BY_AMP_ID",
    "cg": "group_id",
    "ids": [
            "amplitude_id",
            "amplitude_id"
    ],
    "owner": "cohort_owner",
    "published": true
}'

바디 매개변수

매개 변수설명
name필수입니다. 문자열입니다. 코호트의 이름입니다.
app_id필수입니다. 정수입니다. 코호트가 포함된 Amplitude 프로젝트의 식별자입니다.
id_type필수입니다. 문자열입니다. ids 필드에 전달되는 ID 유형입니다. 유효한 옵션은 BY_AMP_ID또는 BY_USER_ID입니다.
cg선택 사항입니다. 문자열입니다. 기존 그룹의 이름을 입력하여 그 기반으로 코호트를 생성합니다.
ids필수입니다. 문자열[]입니다. 코호트에 포함시킬 하나 이상의 사용자 또는 Amplitude ID. id_type필드에 ID 유형을 지정합니다.
owner필수입니다. 문자열입니다. Amplitude에서 코호트 소유자의 로그인 이메일입니다.
published필수입니다. 부울입니다. 코호트가 발견 가능한지 아니면 숨겨져 있는지를 나타냅니다.
skip_save선택 사항입니다. 부울입니다. 업로드를 저장하지 않고 유효성을 검사하려면 true으로 설정합니다. 기본값은 false입니다.
skip_invalid_ids선택 사항입니다. 부울입니다. 유효하지 않은 ID를 건너뛰고 나머지 유효한 ID를 업로드하려면 true로 설정하십시오. 요청에 잘못된 ID가 있는 경우 업로드를 종료하도록 false설정합니다. 기본값은 true입니다.
existing_cohort_id선택 사항입니다. 문자열입니다. 기존 코호트의 ID입니다. 요청에 업로드된 ID는 지정된 코호트의 내용을 대체합니다. 예를 들어 1a2bc3d는 귀하의 코호트 ID이며, 코호트의 URL에서 확인할 수 있습니다https://analytics.amplitude.com/accountname/cohort/1a2bc3d.

응답

응답은 다음 스키마를 가진 JSON 객체입니다.

json
{
  "cohortId": "COHORT_ID",
  "metadata": {
    "matched": 1234,
    "totals": 1232,
    "invalid_ids_sample": ["INVALID_ID1", "INVALID_ID2"]
  }
}

응답 오류

매개 변수유형설명
오류오류 json오류 세부 정보입니다.

코호트 오류 응답 JSON 업로드

매개 변수설명
http_code정수입니다. 사용 가능한 경우 HTTP 오류를 제공합니다.
type문자열입니다. 오류의 유형에 대해 설명합니다.
message문자열입니다. 오류에 대해 설명합니다.
metadataJSON 객체입니다. 오류의 원인을 보다 자세히 설명합니다. 예를 들어 어떤 사용자 ID 값이 잘못되었는지에 대한 내용입니다.

코호트 멤버십 업데이트

ID를 추가 및 제거하여 기존 코호트 멤버십을 점진적으로 업데이트합니다.

curl --location --request POST 'https://amplitude.com/api/3/cohorts/membership' \
--header 'Content-Type: application/json' \
-u '{api_key}:{secret_key}' \
--data-raw '{
    "cohort_id": "COHORT_ID",
    "memberships": [
        {
            "ids": [
                "ID",
                "ID"
            ],
            "id_type": "BY_ID",
            "operation": "ADD"
        },
        {
            "ids": [
                "ID",
                "ID"
            ],
            "id_type": "BY_ID",
            "operation": "REMOVE"
        },
        {
            "ids": [
                "name",
                "name"
            ],
            "id_type": "BY_NAME",
            "operation": "ADD"
        }
    ],
    "skip_invalid_ids": true
}

요청 본문

매개 변수설명
cohort_id필수입니다. 문자열입니다. 기존 코호트의 ID입니다. 요청에 업로드된 ID는 지정된 코호트의 멤버십을 업데이트합니다.
count_group선택 사항입니다. 문자열입니다. 지정된 ID의 수행 회수가 그룹입니다. 수행 회수가 그룹은 해당 코호트의 기존 수행 회수가 그룹과 일치해야 합니다. count_group기본값은 User입니다.
memberships필수입니다. 멤버십 JSON 목록입니다. 추가하거나 제거할 ID를 식별하는 JSON 객체의 배열입니다.
skip_invalid_ids선택 사항입니다. 부울입니다. 요청에 잘못된 ID가 있을 경우 코호트 멤버십을 업데이트하지 않고 요청을 종료하도록 false설정합니다. 유효하지 않은 ID를 건너뛰고 나머지 유효한 ID를 적용하려면 true로 설정하십시오. 기본값은 true입니다.

멤버십 요청 JSON

매개 변수설명
ids필수입니다. 문자열[]입니다. 추가하거나 제거할 ID 목록입니다.
id_type필수입니다. 문자열입니다. ids필드에 전송된 ID 유형입니다. 유효한 옵션은 BY_ID및 BY_NAME입니다. User수행 회수가 그룹의 경우 BY_ID 은 Amplitude ID이고 BY_NAME 은 사용자 ID입니다. 그 외 모든 카운트 그룹의 경우 BY_ID은 그룹 ID이고 BY_NAME 는 그룹 이름입니다.
operation필수입니다. 문자열입니다. ids필드에 적용할 작업입니다. 유효한 옵션은 ADD 및 REMOVE입니다.

응답

매개 변수설명
cohort_id문자열입니다. 멤버십 정보가 업데이트된 기존 코호트의 ID입니다.
memberships_resultmemberships_resultJSON 목록입니다. 멤버십 업데이트 작업의 결과를 식별하는 JSON 객체의 배열입니다.

멤버십 응답 JSON

매개 변수설명
skipped_ids문자열 목록입니다. 멤버십 작업 항목에서 건너뛰는 ID 목록입니다.
id_type문자열입니다. 이 멤버십 작업 항목의 필드에 ids대해 전송된 ID의 종류입니다.
operation문자열입니다. 이 멤버십 작업 항목의 ids필드에 적용된 작업

이 내용이 도움이 되었나요?