> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 오디언스 타겟팅 API

> API 키로 서버에서 오디언스 타겟팅과 타겟팅 옵션, 옵션 조건을 조회하는 방법을 안내합니다.

오디언스 타겟팅 API로 프로젝트의 오디언스 타겟팅과 타겟팅 옵션을 조회할 수 있습니다. [광고 상품 API](https://docs.adrop.io/ko/integrations/ad-products.md)의 `targetings`에 넣을 타겟팅 ID와 옵션 ID를 찾거나, 옵션에 설정한 프로퍼티·이벤트 조건을 확인할 때 사용합니다.

> [!NOTE]
>
> 이 API는 조회만 할 수 있습니다. 오디언스 타겟팅을 만들거나 수정하려면 콘솔을 사용하세요. [오디언스 타겟팅](https://docs.adrop.io/ko/targeting/audience.md)을 참고하세요. 문맥 타겟팅은 [문맥 타겟팅 API](https://docs.adrop.io/ko/integrations/context-targeting/overview.md)로 다룹니다.

***

## 사전 준비

* `audience-targeting:read` 권한(scope)이 있는 API 키가 필요합니다. 이 권한은 콘솔 **\[관리]** > **\[연동]** 메뉴에서 선택할 수 없습니다. 에이드랍에 요청하면 권한을 넣은 키를 발급해 드리며, [광고 상품 API](https://docs.adrop.io/ko/integrations/ad-products.md) 권한도 같은 키에 함께 받을 수 있습니다.

> [!WARNING]
>
> API는 서버에서만 호출하세요. 앱이나 웹 페이지에 API 키를 넣지 마세요.

***

## 기본 정보

| 항목 | 값 |
| - | - |
| Base URL | `https://lake.adrop.io` |
| 인증 | `x-api-key` 헤더에 API 키를 넣습니다. 키가 속한 프로젝트의 타겟팅만 조회할 수 있으며, 다른 프로젝트의 ID는 `404`를 반환합니다. |
| 요청 본문 | 모든 요청은 조회(`GET`)이므로 본문을 넣지 마세요. 본문이 있으면 크기와 관계없이 `413`을 반환합니다. |
| ID 형식 | 영문자, 숫자, `_`, `-`로 된 64자 이하 문자열입니다. |
| 시각 | `createdAt`, `updatedAt`, `segmentedAt`은 epoch 밀리초입니다. ISO 8601 문자열을 쓰는 문맥 타겟팅 API와 형식이 다릅니다. |
| 동시 요청 | 프로젝트당 4건까지 동시에 처리합니다. 같은 프로젝트의 키를 여러 개 써도 합쳐서 셉니다. 넘으면 `429`를 반환합니다. |

`429`를 받으면 `Retry-After` 헤더에 적힌 시간(초)만큼 기다린 뒤 다시 보내세요. 서버가 바쁠 때는 요청을 하나씩 보내도 `429`를 받을 수 있습니다.

***

## 용어

API 경로와 필드 중 일부는 콘솔과 다른 이름을 씁니다. 이 문서는 콘솔의 용어를 씁니다.

| API | 콘솔 용어 | 설명 |
| - | - | - |
| `targeting` | 타겟팅 | "연령대" 같은 오디언스 타겟팅입니다. 이 API는 오디언스 타겟팅만 다룹니다. |
| `category` | 타겟팅 옵션(옵션) | "20대"처럼 타겟팅에 속한 옵션입니다. |
| `type: "collection"` | 옵션 그룹 | 하위 옵션을 묶은 옵션입니다. 일반 옵션은 `type: "atomic"`입니다. |
| `children`, `parent` | 하위 옵션 | 옵션 그룹 안에 있는 옵션입니다. 옵션 그룹의 `children`에는 하위 옵션 목록이, 하위 옵션의 `parent`에는 소속 옵션 그룹이 들어 있습니다. |
| `users` | 오디언스 규모 | 프로젝트 사용자 중 이 옵션에 속하는 사용자 수입니다. |
| `conditions` | 조건 | 옵션에 설정한 프로퍼티·이벤트 조건입니다. |

***

## 엔드포인트

경로는 Base URL 기준입니다. 모든 엔드포인트에 `audience-targeting:read` 권한이 필요합니다.

| 메서드 | 경로 | 설명 |
| - | - | - |
| `GET` | `/audience-targeting` | [타겟팅 목록 조회](#타겟팅-목록-조회) |
| `GET` | `/audience-targeting/{targetingId}` | [타겟팅 조회](#타겟팅-조회) |
| `GET` | `/audience-targeting/{targetingId}/categories` | [옵션 목록 조회](#옵션-목록-조회)(페이지 단위) |
| `GET` | `/audience-targeting/category/{categoryId}` | [옵션 조회](#옵션-조회)(조건 포함) |

***

## 타겟팅 객체

| 필드 | 타입 | 설명 |
| - | - | - |
| `_id` | string | 타겟팅 ID. 광고 상품의 `targetings[].targeting`에 씁니다. |
| `name` | string | 타겟팅 이름 |
| `categoryCount` | number | 하위 옵션을 포함한 옵션 수. 삭제된 옵션이 포함될 수 있어 [옵션 목록 조회](#옵션-목록-조회)로 읽은 수와 다를 수 있습니다. |
| `segmentedAt` | number | 이 타겟팅의 오디언스를 마지막으로 계산한 시각. 아직 계산하지 않았으면 생략됩니다. |
| `createdAt` | number | 타겟팅을 만든 시각 |
| `updatedAt` | number | 타겟팅을 마지막으로 수정한 시각 |

타겟팅 객체에는 옵션이 들어 있지 않습니다. 옵션은 [옵션 목록 조회](#옵션-목록-조회)로 읽습니다.

***

## 타겟팅 목록 조회

프로젝트의 모든 오디언스 타겟팅을 콘솔에 보이는 순서대로, 페이지 나눔 없이 한 번에 반환합니다. 문맥 타겟팅은 포함되지 않습니다.

### 요청

```http theme={null}
GET /audience-targeting
```

### 요청 예시

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting" \
  -H "x-api-key: YOUR_API_KEY"
```

### 응답 예시

`200` 응답으로 [타겟팅 객체](#타겟팅-객체) 배열을 반환합니다.

```json theme={null}
[
  {
    "_id": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
    "name": "Users",
    "categoryCount": 12,
    "segmentedAt": 1790820300000,
    "createdAt": 1790820300000,
    "updatedAt": 1790820300000
  }
]
```

***

## 타겟팅 조회

타겟팅 하나를 반환합니다.

### 요청

```http theme={null}
GET /audience-targeting/{targetingId}
```

### 요청 예시

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting/01JAZ3K9Q8W5T2M4N6P7R8S9TV" \
  -H "x-api-key: YOUR_API_KEY"
```

### 응답

`200` 응답으로 [타겟팅 객체](#타겟팅-객체)를 반환합니다.

### 오류

* `404 TARGETING_NOT_FOUND`: 타겟팅이 없거나, 다른 프로젝트의 타겟팅이거나, 문맥 타겟팅입니다.

***

## 옵션 객체

| 필드 | 타입 | 설명 |
| - | - | - |
| `_id` | string | 옵션 ID. 광고 상품의 `targetings[].policies` 키로 씁니다. |
| `name` | string | 옵션 이름 |
| `type` | string | `atomic`(일반 옵션) 또는 `collection`(옵션 그룹) |
| `parent` | string | 소속 옵션 그룹의 ID. 하위 옵션에만 있습니다. |
| `children` | string\[] | 하위 옵션 ID 중 앞 50개. 옵션 그룹에만 있습니다. |
| `childCount` | number | 하위 옵션 전체 수. 옵션 그룹에만 있습니다. `children`보다 많으면 나머지는 [옵션 목록 조회](#옵션-목록-조회)의 `parent`로 읽습니다. |
| `users` | number | 오디언스 규모. 옵션 목록 조회 응답에만 있습니다. |
| `operable` | boolean | 조건에 쓴 프로퍼티가 지금의 프로퍼티 설정(필드·타입·연산자)과 맞는지 여부. [조건을 읽을 수 없는 경우](#조건을-읽을-수-없는-경우)를 참고하세요. |
| `createdAt` | number | 옵션을 만든 시각 |
| `updatedAt` | number | 옵션을 마지막으로 수정한 시각 |

[옵션 조회](#옵션-조회)는 여기에 `targeting`(소속 타겟팅 ID), `convertible`, `conditions`를 더해 반환합니다.

***

## 옵션 목록 조회

타겟팅의 최상위 옵션을 콘솔에 보이는 순서대로 페이지 단위로 반환합니다. 옵션 그룹의 하위 옵션은 `parent`로 따로 읽습니다.

### 요청

```http theme={null}
GET /audience-targeting/{targetingId}/categories
```

### 쿼리 파라미터

| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
| - | - | :-: | - | - |
| `limit` | number | - | `100` | 한 번에 받을 옵션 수(1\~1,000) |
| `next` | string | - | - | 다음 페이지 커서. 앞 응답의 `next`를 그대로 넣습니다. 첫 페이지는 생략합니다. |
| `parent` | string | - | - | 옵션 그룹 ID. 넣으면 그 옵션 그룹의 하위 옵션을 그룹 안의 순서대로 반환합니다. |

### 요청 예시

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting/01JAZ3K9Q8W5T2M4N6P7R8S9TV/categories?limit=100" \
  -H "x-api-key: YOUR_API_KEY"
```

### 응답 예시

`200` 응답으로 `items`([옵션 객체](#옵션-객체) 목록)와 `next`(다음 페이지 커서)를 반환합니다. `next`가 없으면 마지막 페이지입니다.

```json theme={null}
{
  "items": [
    {
      "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K",
      "name": "Korea",
      "type": "atomic",
      "users": 1200,
      "operable": true,
      "createdAt": 1790820300000,
      "updatedAt": 1790820300000
    },
    {
      "_id": "01JAZ3KC3D4E5F6G7H8J9K0M1N",
      "name": "Asia",
      "type": "collection",
      "users": 5000,
      "operable": true,
      "children": ["01JAZ3KB2C3D4E5F6G7H8J9K0M", "01JAZ3KE5F6G7H8J9K0M1N2P3Q"],
      "childCount": 2,
      "createdAt": 1790820300000,
      "updatedAt": 1790820300000
    }
  ],
  "next": "01JAZ3KC3D4E5F6G7H8J9K0M1N"
}
```

* 옵션 목록에는 조건이 없습니다. 조건은 [옵션 조회](#옵션-조회)로 읽습니다.
* `users`가 `0`이면 아직 사용자 통계가 쌓이지 않았거나 통계를 일시적으로 읽지 못한 것일 수 있습니다. `0` 하나로 옵션을 판단하지 말고, 의심되면 잠시 뒤 다시 조회하세요.
* 페이지를 읽는 도중 옵션이 추가·삭제·이동되면 결과가 실제와 달라질 수 있습니다. `next`로 넣은 옵션이 그 사이 삭제되거나 옮겨지면 `404 TARGETING_CATEGORY_NOT_FOUND`를 반환하니, 첫 페이지부터 다시 읽으세요.

### 오류

* `400 TARGETING_CATEGORY_NOT_SUPPORTED`: `parent`가 옵션 그룹이 아닌 일반 옵션입니다.
* `404 TARGETING_NOT_FOUND`: 타겟팅이 없거나, 다른 프로젝트의 타겟팅이거나, 문맥 타겟팅입니다.
* `404 TARGETING_CATEGORY_NOT_FOUND`: `next`가 이 타겟팅의 최상위 옵션이 아니거나(삭제·이동됨), `parent`가 이 타겟팅의 옵션이 아닙니다.

***

## 옵션 조회

옵션 하나를 조건과 함께 반환합니다.

### 요청

```http theme={null}
GET /audience-targeting/category/{categoryId}
```

### 요청 예시

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting/category/01JAZ3KA1B2C3D4E5F6G7H8J9K" \
  -H "x-api-key: YOUR_API_KEY"
```

### 응답 예시

`200` 응답으로 [옵션 객체](#옵션-객체)에 다음 필드를 더해 반환합니다. `users`는 들어 있지 않습니다.

| 필드 | 타입 | 설명 |
| - | - | - |
| `targeting` | string | 옵션이 속한 타겟팅 ID |
| `convertible` | boolean | 조건을 `conditions`로 나타낼 수 있는지 여부 |
| `conditions` | object | 옵션의 조건. `convertible`이 `true`일 때만 있습니다. [조건](#조건)을 참고하세요. |

```json theme={null}
{
  "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K",
  "name": "Korean adults",
  "type": "atomic",
  "operable": true,
  "targeting": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
  "convertible": true,
  "conditions": {
    "all": [
      { "field": "country", "op": "is", "values": ["KR"] },
      { "field": "age", "op": "greater_than_or_equals", "values": [20] }
    ]
  },
  "createdAt": 1790820300000,
  "updatedAt": 1790820300000
}
```

이 프로젝트의 오디언스 타겟팅에 속한 옵션만 조회할 수 있습니다.

### 오류

* `404 TARGETING_CATEGORY_NOT_FOUND`: 옵션이 없거나, 다른 프로젝트의 옵션이거나, 오디언스 타겟팅에 속한 옵션이 아닙니다.

***

## 조건

`conditions`는 옵션의 조건을 `all`(그리고)과 `any`(또는)로 묶은 트리입니다. 광고 송출에 실제로 쓰이는 조건과 같은 의미로 나타냅니다.

### 노드

| 노드 | 의미 |
| - | - |
| `{ "all": [...] }` | 안의 조건을 모두 만족 |
| `{ "any": [...] }` | 안의 조건 중 하나 이상을 만족 |
| 프로퍼티 조건, 이벤트 조건 | 아래 설명 |

* 가장 바깥은 항상 `all` 또는 `any`입니다. 조건이 하나뿐이면 `{ "all": [조건] }`입니다.
* 같은 종류의 노드를 겹쳐 쓰지 않습니다. 예를 들어 `all` 안에 `all`이 바로 오지 않습니다.

예를 들어 다음 조건은 "(국가가 KR 또는 JP이고, `level`이 10 이상이고, 최근 30일 안에 `item_category`가 `book`인 구매를 1회 이상 한 사용자) 또는 (성별이 F인 사용자)"입니다.

```json theme={null}
{
  "any": [
    {
      "all": [
        { "field": "country", "op": "is", "values": ["KR", "JP"] },
        { "field": "custom.level", "op": "greater_than_or_equals", "values": [10] },
        {
          "event": "purchase",
          "action": "did",
          "measure": "total_events",
          "op": "greater_than_or_equals",
          "value": 1,
          "where": [{ "param": "item_category", "op": "is", "values": ["book"] }],
          "recency": "30D"
        }
      ]
    },
    { "field": "gender", "op": "is", "values": ["F"] }
  ]
}
```

### 프로퍼티 조건

```json theme={null}
{ "field": "country", "op": "is", "values": ["KR"] }
```

| 필드 | 설명 |
| - | - |
| `field` | 프로퍼티. 기본 프로퍼티는 `country`, `language`, `gender`, `age`, `consent`이고, 커스텀 프로퍼티는 `custom.<프로퍼티 이름>`입니다. [프로퍼티](https://docs.adrop.io/ko/targeting/property.md)를 참고하세요. |
| `op` | 연산자. 아래 표를 참고하세요. |
| `values` | 비교할 값. 개수는 연산자에 따라 다릅니다. `is`와 `is_not`은 여러 개, `between`과 `not_between`은 `[최솟값, 최댓값]` 두 개, `is_true`와 `is_false`는 `[]`, 그 밖에는 한 개입니다. |
| `match` | 값이 배열인 커스텀 프로퍼티에만 있습니다. `any`면 배열 요소 중 하나라도, `all`이면 모든 요소가 조건을 만족해야 합니다. |

| 프로퍼티 타입 | 연산자 |
| - | - |
| 문자열 | `is`(값 중 하나와 같음), `is_not`(값 중 어느 것과도 다름, 값이 없는 사용자 포함), `contains`, `does_not_contains`, `starts_with`, `ends_with` |
| 숫자 | `is`, `is_not`, `equals`, `not_equals`, `greater_than`, `greater_than_or_equals`, `less_than`, `less_than_or_equals`, `between`, `not_between` |
| 불리언 | `is_true`, `is_false` |
| 날짜 | `last`(최근 기간 이내), `before_the_last`, `next`, `after_the_next`(값은 `30D`, `2W`, `1M` 같은 기간), `before`, `after`(값은 날짜 문자열) |

### 이벤트 조건

```json theme={null}
{ "event": "purchase", "action": "did", "measure": "total_events", "op": "greater_than_or_equals", "value": 1, "recency": "30D" }
```

| 필드 | 설명 |
| - | - |
| `event` | 이벤트 이름: `app_open`, `sign_up`, `push_clicks`, `page_view`, `click`, `view_item`, `add_to_wishlist`, `add_to_cart`, `begin_checkout`, `purchase`, `view_content`, `begin_lead_form`, `generate_lead`. [이벤트](https://docs.adrop.io/ko/targeting/event.md)를 참고하세요. |
| `action` | `did`면 기간 안에 이벤트를 했고 집계 값이 `op`와 `value`를 만족한 사용자입니다. `did_not_do`면 기간 안에 이벤트를 하지 않은 사용자이며, `measure`, `op`, `value`가 없습니다. |
| `measure` | 집계 방식. `"total_events"`(이벤트 횟수) 또는 `{ "type": "sum", "param": "price" }`처럼 이벤트 파라미터 값의 `sum`(합계), `average`(평균), `minimum`(최솟값), `maximum`(최댓값), `distinct_count`(고유 개수)입니다. |
| `op` | `equals`, `not_equals`, `greater_than`, `greater_than_or_equals`, `less_than`, `less_than_or_equals` |
| `value` | 비교할 숫자 |
| `where` | 이벤트 파라미터 조건 목록 `[{ "param", "op", "values" }]`. 모두 만족해야 합니다. |
| `recency` | 기간. 숫자와 단위 `H`(시간), `D`(일), `W`(주), `M`(월)로 나타냅니다(예: `30D`). 이 기간 안의 이벤트만 봅니다. |

콘솔에서 이벤트 조건을 여러 개 이으면 광고 송출에서는 정해진 규칙으로 결합되므로, 콘솔에서 **or**로 이은 조건이 트리에서는 `all`로 나올 수 있습니다. 트리의 `all`과 `any`를 그대로 따르세요.

### 옵션 그룹의 조건

옵션 그룹은 자기 조건이 없고, 하위 옵션의 조건 중 하나를 만족하면 포함됩니다. 그래서 옵션 그룹의 `conditions`는 하위 옵션 조건을 `any`로 합친 것입니다.

* 하위 옵션의 조건이 `any`로 시작하면 그 안의 조건이 바깥 `any`에 바로 들어가므로, 갈래 수가 하위 옵션 수와 다를 수 있습니다.
* 하위 옵션이 하나뿐이면 `any`로 감싸지 않고 그 하위 옵션의 조건을 그대로 반환합니다.
* 조건이 없는 하위 옵션은 건너뜁니다.

### 조건을 읽을 수 없는 경우

| 필드 | 의미 | `false`일 때 |
| - | - | - |
| `convertible` | 저장된 조건을 광고 송출과 같은 의미의 트리로 나타낼 수 있는지 여부 | `conditions`가 없습니다. 조건을 해석하지 말고 콘솔에서 확인하세요. |
| `operable` | 조건에 쓴 프로퍼티가 지금의 프로퍼티 설정과 맞는지 여부 | 조건에 쓴 프로퍼티가 삭제됐거나 타입이 바뀌어 지금 설정으로는 운영할 수 없습니다. 옵션 그룹은 하위 옵션 중 하나라도 맞지 않으면 `false`입니다. |

두 값은 서로 관계없습니다. `convertible`이 `true`이면서 `operable`이 `false`일 수도 있습니다.

***

## 오류 처리

오류 응답에는 `statusCode`가 들어 있고, 아래 표에서 `errorCode` 칸이 `-`가 아닌 오류에는 `errorCode`도 들어 있습니다. 처리 방식은 `errorCode`로 나누고, `errorCode`가 없으면 `statusCode`로 나누세요. 요청 형식 오류(`VALIDATION_FAILED`)는 잘못된 위치를 `detail.errors[]`의 `path`로 알려 줍니다.

| 상태 | `errorCode` | 원인 |
| - | - | - |
| `400` | `VALIDATION_FAILED` | ID나 `next`, `parent`의 형식이 잘못됐거나, `limit`이 범위를 벗어났거나, 모르는 쿼리 파라미터를 보냈습니다. |
| `400` | `TARGETING_CATEGORY_NOT_SUPPORTED` | `parent`가 옵션 그룹이 아닌 일반 옵션입니다. |
| `401` | - | API 키가 없거나 잘못됐거나 폐기됐습니다. |
| `403` | - | `audience-targeting:read` 권한이 없습니다. |
| `404` | `TARGETING_NOT_FOUND` | 타겟팅이 없거나, 다른 프로젝트의 타겟팅이거나, 문맥 타겟팅입니다. |
| `404` | `TARGETING_CATEGORY_NOT_FOUND` | 옵션이 없거나, 다른 프로젝트의 옵션이거나, 오디언스 타겟팅의 옵션이 아닙니다. 옵션 목록 조회에서는 `next`나 `parent`가 이 타겟팅의 옵션이 아닐 때도 반환합니다. |
| `413` | - | 조회 요청에 본문을 넣었습니다. |
| `429` | `TOO_MANY_CONCURRENT_REQUESTS` | 동시 요청 한도를 넘었거나 서버가 바쁩니다. `Retry-After` 헤더의 시간(초)만큼 기다린 뒤 다시 보내세요. |
| `502` | - | 서버 내부 통신에 문제가 있습니다. |

***

## 한도

| 항목 | 한도 |
| - | - |
| 옵션 목록 페이지 크기 | 1\~1,000개(기본 100) |
| 옵션 그룹의 `children` | 앞 50개. 나머지는 `parent`로 조회 |
| 동시 요청 | 프로젝트당 4건 |
| 응답 수신 | 30초 안에 응답을 다 받지 못하면 서버가 연결을 끊습니다. 하위 옵션이 많은 옵션 그룹은 응답이 클 수 있습니다. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.