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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Ad Groups API

> 광고 그룹은 광고 캠페인 안에 위치하며 광고의 게재를 제어합니다. 광고의 오디언스, 일정, 예산을 설정합니다.

광고 그룹은 [광고 캠페인](https://docs.whop.com/ko/api-reference/ad-campaigns/ad-campaign) 안에 위치하며 [광고](https://docs.whop.com/ko/api-reference/ads/ad)의 게재를 제어합니다. 광고의 오디언스, 일정, 예산을 설정합니다.

Ad Groups API를 사용하면 캠페인에 광고 그룹을 생성하고, 타기팅 및 게재 설정을 나열하거나 조회하고, 예산이나 타기팅을 업데이트하고, 더 이상 게재하지 않을 그룹을 삭제하고, 게재를 일시 중지하거나 재개할 수 있습니다.

## 엔드포인트

| 엔드포인트 | 요청 |
| - | - |
| [광고 그룹 목록 조회](https://docs.whop.com/ko/api-reference/ad-groups/list-ad-groups.md) | GET `/ad_groups` |
| [광고 그룹 조회](https://docs.whop.com/ko/api-reference/ad-groups/retrieve-an-ad-group.md) | GET `/ad_groups/{id}` |
| [광고 그룹 생성](https://docs.whop.com/ko/api-reference/ad-groups/create-an-ad-group.md) | POST `/ad_groups` |
| [광고 그룹 복제](https://docs.whop.com/ko/api-reference/ad-groups/duplicate-an-ad-group.md) | POST `/ad_groups/{id}/duplicate` |
| [광고 그룹 일시 중지](https://docs.whop.com/ko/api-reference/ad-groups/pause-an-ad-group.md) | POST `/ad_groups/{id}/pause` |
| [광고 그룹 일시 중지 해제](https://docs.whop.com/ko/api-reference/ad-groups/unpause-an-ad-group.md) | POST `/ad_groups/{id}/unpause` |
| [광고 그룹 업데이트](https://docs.whop.com/ko/api-reference/ad-groups/update-an-ad-group.md) | PATCH `/ad_groups/{id}` |
| [광고 그룹 삭제](https://docs.whop.com/ko/api-reference/ad-groups/delete-an-ad-group.md) | DELETE `/ad_groups/{id}` |

## 타기팅 제한

광고 그룹은 [광고 가이드에 나열된 국가](https://docs.whop.com/ko/developer/ads/overview.md#countries-you-cannot-target)를 타기팅할 수 없습니다. 광고 그룹을 생성하거나 타기팅 국가를 업데이트하는 요청에서 `regions.include.countries`에 차단된 국가가 포함되면 요청이 거부됩니다.

## 속성

**id** `string` *required*

`adgrp_` 접두사가 붙은 광고 그룹의 고유 식별자입니다.

**ad\_campaign** `object` *required*

이 광고 그룹이 속한 광고 캠페인입니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 참조된 엔터티의 ID입니다.

**added\_to\_cart\_value** `number` *required*

장바구니 담기 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**added\_to\_carts** `number` *required*

Whop 픽셀에 귀속된 장바구니 담기 이벤트 수(라스트 클릭 기준)입니다.

**audiences** `object` *required*

이 광고 그룹이 게재 대상으로 하거나 제외하는 저장된 오디언스입니다.

> [accordion] 속성
>
> **exclude** `string[]` *required*
>
> 게재에서 제외되는 저장된 오디언스의 ID이며, `adaud_` 접두사가 붙습니다.
>
> **include** `string[]` *required*
>
> 광고 그룹이 게재 대상으로 하는 저장된 오디언스의 ID이며, `adaud_` 접두사가 붙습니다.

**bid\_type** `string | null` *required*

광고 경매에서 게재 입찰가를 설정하는 방식입니다. 목표 기반 전략은 `desired_cost_per_result`를 사용합니다.

사용 가능한 옵션: `minimum_cost`, `average_target`, `maximum_target`

**budget\_amount** `number | null` *required*

이 광고 그룹의 예산(USD)으로, 예산이 저장되고 청구되는 통화입니다. 대신 캠페인에 예산이 설정되어 있으면 `null`입니다.

**budget\_amount\_local** `number | null` *required*

계정의 광고 보고 통화로 표시하기 위해 오늘 환율로 `budget_currency`로 나타낸 동일한 예산입니다. `budget_amount`가 `null`이면 `null`입니다.

**budget\_currency** `string` *required*

`budget_amount_local`의 ISO 4217 코드로, 계정의 `ads_reporting_currency` 설정입니다. 계정이 변경하지 않았다면 `usd`입니다.

**budget\_type** `string | null` *required*

`budget_amount`를 하루 단위로 지출하는지(`daily`), 광고 그룹 전체 기간에 걸쳐 지출하는지(`lifetime`) 여부입니다. `lifetime` 광고 그룹에는 시작 시점으로부터 최소 24시간 이후인 `ends_at`도 필요합니다.

사용 가능한 옵션: `daily`, `lifetime`

**click\_through\_rate** `number` *required*

클릭 수를 노출 수로 나눈 값으로, 0과 1 사이입니다.

**clicks** `number` *required*

클릭 수입니다.

**completed\_registration\_value** `number` *required*

등록 완료 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**completed\_registrations** `number` *required*

Whop 픽셀에 귀속된 등록 완료 이벤트 수(라스트 클릭 기준)입니다.

**contact\_value** `number` *required*

문의 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**contacts** `number` *required*

Whop 픽셀에 귀속된 문의 이벤트 수(라스트 클릭 기준)입니다.

**conversion\_event** `string | null` *required*

최적화 대상 픽셀 이벤트입니다. 표준 이벤트 또는 임의의 맞춤 픽셀 이벤트 이름입니다.

**cost\_per\_added\_to\_cart** `number | null` *required*

지출을 귀속된 장바구니 담기 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

**cost\_per\_click** `number` *required*

지출을 클릭 수로 나눈 값입니다. 클릭이 없으면 0입니다.

**cost\_per\_completed\_registration** `number | null` *required*

지출을 귀속된 등록 완료 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

**cost\_per\_contact** `number | null` *required*

지출을 귀속된 문의 이벤트 수로 나눈 값입니다. 문의가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

**cost\_per\_lead** `number | null` *required*

지출을 귀속된 리드 수로 나눈 값입니다. 리드가 목표가 아니고 귀속된 리드가 없으면 null입니다.

**cost\_per\_mille** `number` *required*

노출 1,000회당 지출입니다. 노출이 없으면 0입니다.

**cost\_per\_purchase** `number | null` *required*

지출을 귀속된 구매 수로 나눈 값입니다. 구매가 목표가 아니고 귀속된 구매가 없으면 null입니다.

**cost\_per\_result** `number | null` *required*

지출을 Whop 픽셀에 귀속된 결과 수로 나눈 값입니다. Whop에 귀속될 수 있는 항목을 최적화하지 않으면 null입니다.

**cost\_per\_schedule** `number | null` *required*

지출을 귀속된 일정 예약 이벤트 수로 나눈 값입니다. 일정 예약이 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

**cost\_per\_submitted\_application** `number | null` *required*

지출을 귀속된 신청서 제출 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

**cost\_per\_unique\_click** `number | null` *required*

지출을 고유 클릭 수로 나눈 값입니다. 고유 클릭이 없으면 null입니다.

**cost\_per\_viewed\_content** `number | null` *required*

지출을 귀속된 콘텐츠 조회 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

**created\_at** `string` *required*

광고 그룹이 생성된 시각(ISO 8601 타임스탬프)입니다.

**custom\_conversions** `number` *required*

모든 맞춤 이벤트 이름에 걸쳐 Whop 픽셀에 귀속된 맞춤(판매자 정의) 전환 이벤트 수(라스트 클릭 기준)입니다.

**custom\_event\_counts** `object` *required*

Whop 픽셀에 귀속된 맞춤 전환으로, 이벤트 이름을 키로, 라스트 클릭 기준 횟수를 값으로 가집니다. 귀속된 이름 있는 맞춤 이벤트가 없으면 비어 있습니다. 이름 없이 발생한 맞춤 이벤트는 custom\_conversions에는 집계되지만 여기서는 제외되므로, 이 값들의 합은 최대 custom\_conversions입니다.

**custom\_event\_values** `object` *required*

custom\_event\_counts와 마찬가지로 이벤트 이름을 키로 하여 각 맞춤 이벤트에 귀속된 전환 가치입니다. whop.track에 전달된 값을 USD로 정규화해 합산하며, 값 없이 발생한 이벤트는 0으로 계산됩니다.

**delivery\_schedule** `object | null` *required*

요일을 키로 하여 광고 그룹이 매주 게재되는 시간입니다. 게재하지 않는 요일은 생략됩니다. 모든 시간에 게재하면 `null`입니다. 일부 플랫폼에서는 일정을 사용하려면 광고 그룹에, 또는 캠페인이 예산을 보유한 경우 캠페인에 lifetime `budget_type`이 필요합니다.

> [accordion] 속성
>
> **friday** `object[]`
>
> 광고 그룹이 금요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.
>
> > [accordion] 속성
> >
> > **end** `string` *required*
> >
> > 게재가 종료되는 시각으로, 24시간제 `HH:00` 형식이며 자정은 최대 `24:00`입니다.
> > `start`보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
> >
> > **start** `string` *required*
> >
> > 게재가 시작되는 시각으로, `00:00`부터 `23:00`까지의 24시간제 `HH:00` 형식입니다.
>
> **monday** `object[]`
>
> 광고 그룹이 월요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.
>
> > [accordion] 속성
> >
> > **end** `string` *required*
> >
> > 게재가 종료되는 시각으로, 24시간제 `HH:00` 형식이며 자정은 최대 `24:00`입니다.
> > `start`보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
> >
> > **start** `string` *required*
> >
> > 게재가 시작되는 시각으로, `00:00`부터 `23:00`까지의 24시간제 `HH:00` 형식입니다.
>
> **saturday** `object[]`
>
> 광고 그룹이 토요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.
>
> > [accordion] 속성
> >
> > **end** `string` *required*
> >
> > 게재가 종료되는 시각으로, 24시간제 `HH:00` 형식이며 자정은 최대 `24:00`입니다.
> > `start`보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
> >
> > **start** `string` *required*
> >
> > 게재가 시작되는 시각으로, `00:00`부터 `23:00`까지의 24시간제 `HH:00` 형식입니다.
>
> **sunday** `object[]`
>
> 광고 그룹이 일요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.
>
> > [accordion] 속성
> >
> > **end** `string` *required*
> >
> > 게재가 종료되는 시각으로, 24시간제 `HH:00` 형식이며 자정은 최대 `24:00`입니다.
> > `start`보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
> >
> > **start** `string` *required*
> >
> > 게재가 시작되는 시각으로, `00:00`부터 `23:00`까지의 24시간제 `HH:00` 형식입니다.
>
> **thursday** `object[]`
>
> 광고 그룹이 목요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.
>
> > [accordion] 속성
> >
> > **end** `string` *required*
> >
> > 게재가 종료되는 시각으로, 24시간제 `HH:00` 형식이며 자정은 최대 `24:00`입니다.
> > `start`보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
> >
> > **start** `string` *required*
> >
> > 게재가 시작되는 시각으로, `00:00`부터 `23:00`까지의 24시간제 `HH:00` 형식입니다.
>
> **tuesday** `object[]`
>
> 광고 그룹이 화요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.
>
> > [accordion] 속성
> >
> > **end** `string` *required*
> >
> > 게재가 종료되는 시각으로, 24시간제 `HH:00` 형식이며 자정은 최대 `24:00`입니다.
> > `start`보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
> >
> > **start** `string` *required*
> >
> > 게재가 시작되는 시각으로, `00:00`부터 `23:00`까지의 24시간제 `HH:00` 형식입니다.
>
> **wednesday** `object[]`
>
> 광고 그룹이 수요일에 게재되는 시간대로, 시간순으로 정렬됩니다. 해당 요일에 게재하지 않으면 생략됩니다.
>
> > [accordion] 속성
> >
> > **end** `string` *required*
> >
> > 게재가 종료되는 시각으로, 24시간제 `HH:00` 형식이며 자정은 최대 `24:00`입니다.
> > `start`보다 늦어야 하며, 자정을 넘는 시간대는 이틀로 나뉩니다.
> >
> > **start** `string` *required*
> >
> > 게재가 시작되는 시각으로, `00:00`부터 `23:00`까지의 24시간제 `HH:00` 형식입니다.

**delivery\_status** `string` *required*

이 광고 그룹의 광고가 현재 게재 중인지 여부와, 게재 중이 아니라면 그 이유입니다. 여러 상태가 동시에 해당하면 우선순위가 가장 높은 상태가 반환됩니다.

사용 가능한 옵션: `all_ads_rejected`, `rejected`, `draft`, `campaign_paused`, `paused`, `in_review`, `processing`, `revise_content`, `issues`, `scheduled`, `completed`, `learning`, `active`

**demographics** `object` *required*

연령, 성별 및 자동 오디언스 타기팅입니다.

> [accordion] 속성
>
> **automatic** `boolean` *required*
>
> 자동 오디언스 타기팅 사용 여부입니다. `true`이면 설정한 연령과 성별을 제안으로 취급해, 그 범위를 넘어서까지 게재될 수 있습니다.
>
> **gender** `string` *required*
>
> 타기팅하는 성별입니다.
>
> 사용 가능한 옵션: `all`, `male`, `female`
>
> **maximum\_age** `number | null` *required*
>
> 타기팅하는 최고 연령입니다. 최댓값이 설정되지 않으면 `null`입니다.
>
> **minimum\_age** `number | null` *required*
>
> 타기팅하는 최저 연령입니다. 최솟값이 설정되지 않으면 `null`입니다.

**desired\_cost\_per\_result** `number | null` *required*

목표로 하는(`average_target`) 또는 절대 초과하지 않을(`maximum_target`) 결과당 비용입니다. `minimum_cost` 입찰에서는 `null`입니다.

**devices** `object` *required*

타기팅하는 기기 플랫폼과 운영 체제입니다.

> [accordion] 속성
>
> **operating\_systems** `object[]` *required*
>
> 타기팅하는 운영 체제입니다. 비어 있으면 모든 운영 체제를 타기팅합니다.
>
> > [accordion] 속성
> >
> > **minimum\_version** `string`
> >
> > 타기팅하는 최저 OS 버전으로, `18.0` 등입니다. 모든 버전이 해당하면 없습니다.
> >
> > **os** `string` *required*
> >
> > 타기팅하는 운영 체제입니다.
> >
> > 사용 가능한 옵션: `ios`, `android`
>
> **platforms** `string[]` *required*
>
> 타기팅하는 기기 유형입니다. 비어 있으면 모든 기기를 타기팅합니다.
>
> 사용 가능한 옵션: `mobile`, `desktop`

**ends\_at** `string | null` *required*

광고 그룹 게재가 종료되는 시각(ISO 8601 타임스탬프)입니다. 일시 중지할 때까지 게재되면 `null`입니다.

**frequency** `number | null` *required*

노출 수를 도달 수로 나눈 값입니다.

**impressions** `number` *required*

노출 수입니다.

**issues** `object[]` *required*

이 광고 그룹과 그 광고에 영향을 주는 미해결 이슈입니다. 없으면 비어 있습니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 이슈의 고유 식별자입니다.
>
> **category** `string` *required*
>
> 이슈의 종류입니다. 게재에 관한 정보, 경고 또는 조치가 필요한 오류 중 하나입니다.
>
> 사용 가능한 옵션: `information`, `warning`, `error`
>
> **message** `string` *required*
>
> 이슈의 내용과 해결 방법에 대한 설명입니다.
>
> **resource\_id** `string | null` *required*
>
> 이슈가 연결된 캠페인, 광고 그룹 또는 광고의 ID입니다.
>
> **resource\_type** `string` *required*
>
> 이슈가 연결된 리소스의 유형입니다.
>
> 사용 가능한 옵션: `ad_campaign`, `ad_group`, `ad`
>
> **title** `string` *required*
>
> 크리에이터에게 표시되는 이슈의 짧은 제목입니다. 콘텐츠 검토 거부 시 지목된 규칙 또는 일반 레이블입니다.

**keywords** `object[]`

이 광고 그룹의 광고가 표시될 수 있는 검색어와 절대 표시되지 않는 검색어입니다. 검색 캠페인 전용이며, 게재 시작 전에 각 광고 그룹에 최소 하나가 필요합니다.

> [accordion] 속성
>
> **match\_type** `string` *required*
>
> 검색어가 얼마나 정확히 일치해야 하는지입니다. `broad`는 관련 검색에도 도달하고, `phrase`는 구문의 의미가 포함되어야 하며, `exact`는 검색어와 의미가 같아야 합니다. 기본값은 `broad`입니다.
>
> 사용 가능한 옵션: `broad`, `phrase`, `exact`
>
> **negative** `boolean` *required*
>
> 이 검색어가 광고를 노출 대상으로 만드는 대신 광고가 표시되지 않도록 하는지 여부입니다. 기본값은 `false`입니다.
>
> **text** `string` *required*
>
> 검색어로, 최대 80자, 10단어입니다.

**languages** `string[]` *required*

`en`이나 `es` 같은 ISO 639 코드로 나타낸 타기팅 언어입니다. ISO 코드가 없는 지역별 로캘은 숫자 로캘 키로 표시됩니다. 비어 있으면 모든 언어를 타기팅합니다.

**lead\_value** `number` *required*

리드 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**leads** `number` *required*

Whop 픽셀에 귀속된 리드 수(라스트 클릭 기준)입니다.

**learning\_progress** `object | null` *required*

이 광고 그룹의 학습 단계에 필요한 전환을 향한 진행 상황입니다. 학습 중이거나 학습 제한 상태이고 유효한 집계가 있을 때만 값이 있으며, 그렇지 않으면 null입니다. 임곗값에 도달했다고 해서 게재 상태가 결정되지는 않습니다.

> [accordion] 속성
>
> **conversion\_threshold** `integer` *required*
>
> 이 광고 그룹의 학습 단계에 필요한 전환 수입니다. 게재 중에 변경될 수 있습니다.
>
> **conversions** `integer` *required*
>
> 이 광고 그룹의 학습 단계 중 마지막 주요 편집 이후 집계된 전환 수입니다.
>
> **progress\_percent** `number` *required*
>
> 전환 수를 임곗값으로 나눈 백분율로, 0–100 범위로 제한됩니다. 광고 그룹의 `delivery_status`가 기준이 됩니다.

**link\_clicks** `number` *required*

광고를 클릭한 사람들이 도착 페이지에서 발생시킨 페이지 조회 수로, Whop 픽셀이 기록합니다. 모든 광고 플랫폼에서 동일한 방식으로 집계됩니다.

**purchase\_value** `number` *required*

픽셀에 귀속된 구매의 USD 가치입니다.

**purchases** `number` *required*

Whop 픽셀에 귀속된 구매 수(라스트 클릭 기준)입니다.

**reach** `number` *required*

이를 본 고유 사용자 수입니다.

**regions** `object` *required*

타기팅 및 제외 위치입니다.

> [accordion] 속성
>
> **exclude** `object` *required*
>
> 타기팅에서 제외되는 위치입니다. 국가 그룹은 제외할 수 없습니다.
>
> > [accordion] 속성
> >
> > **cities** `object[]` *required*
> >
> > 위치 분류 체계를 키로 하는 도시입니다.
> >
> > > [accordion] 속성
> > >
> > > **key** `string` *required*
> > >
> > > 위치 분류 체계에서의 도시 키입니다.
> > >
> > > **name** `string`
> > >
> > > `Austin` 같은 도시 이름입니다. 위치 분류 체계에 이름이 없으면 없습니다.
> >
> > **countries** `string[]` *required*
> >
> > `US` 같은 ISO 3166-1 alpha-2 코드로 나타낸 국가입니다.
> >
> > **country\_groups** `string[]` *required*
> >
> > `worldwide`나 `europe` 같은 다국가 그룹입니다.
> >
> > **custom\_locations** `object[]` *required*
> >
> > 각각 좌표와 반경으로 이루어진 원형 영역입니다.
> >
> > > [accordion] 속성
> > >
> > > **country\_code** `string`
> > >
> > > 지점이 속한 국가의 ISO 3166-1 alpha-2 코드입니다. 캠페인이 광고 세트가 도달하는 국가를 선언해야 하는 특별 광고 카테고리에서는 이 값을 보내세요.
> > >
> > > **distance\_unit** `string` *required*
> > >
> > > `radius`의 단위입니다.
> > >
> > > 사용 가능한 옵션: `mile`, `kilometer`
> > >
> > > **latitude** `number` *required*
> > >
> > > 중심점의 위도입니다.
> > >
> > > **longitude** `number` *required*
> > >
> > > 중심점의 경도입니다.
> > >
> > > **name** `string`
> > >
> > > 도시나 주소 같은 위치 레이블입니다. 위치에 레이블이 없으면 없습니다.
> > >
> > > **radius** `number` *required*
> > >
> > > `distance_unit` 단위의 중심점 주변 반경입니다.
> >
> > **regions** `string[]` *required*
> >
> > `US-CA` 같은 ISO 3166-2 코드로 나타낸 미국 주 및 DC입니다. 미국 영토(`PR`, `GU`, `VI`, `AS`, `MP`)와 미국 외 모든 지역은 `countries`를 통해 타기팅합니다.
> >
> > **zips** `string[]` *required*
> >
> > `US:78756`처럼 `COUNTRY:CODE` 형식을 키로 하는 ZIP 및 우편번호입니다.
>
> **include** `object` *required*
>
> 광고 그룹이 타기팅하는 위치입니다.
>
> > [accordion] 속성
> >
> > **cities** `object[]` *required*
> >
> > 위치 분류 체계를 키로 하는 도시입니다.
> >
> > > [accordion] 속성
> > >
> > > **key** `string` *required*
> > >
> > > 위치 분류 체계에서의 도시 키입니다.
> > >
> > > **name** `string`
> > >
> > > `Austin` 같은 도시 이름입니다. 위치 분류 체계에 이름이 없으면 없습니다.
> >
> > **countries** `string[]` *required*
> >
> > `US` 같은 ISO 3166-1 alpha-2 코드로 나타낸 국가입니다.
> >
> > **country\_groups** `string[]` *required*
> >
> > `worldwide`나 `europe` 같은 다국가 그룹입니다.
> >
> > **custom\_locations** `object[]` *required*
> >
> > 각각 좌표와 반경으로 이루어진 원형 영역입니다.
> >
> > > [accordion] 속성
> > >
> > > **country\_code** `string`
> > >
> > > 지점이 속한 국가의 ISO 3166-1 alpha-2 코드입니다. 캠페인이 광고 세트가 도달하는 국가를 선언해야 하는 특별 광고 카테고리에서는 이 값을 보내세요.
> > >
> > > **distance\_unit** `string` *required*
> > >
> > > `radius`의 단위입니다.
> > >
> > > 사용 가능한 옵션: `mile`, `kilometer`
> > >
> > > **latitude** `number` *required*
> > >
> > > 중심점의 위도입니다.
> > >
> > > **longitude** `number` *required*
> > >
> > > 중심점의 경도입니다.
> > >
> > > **name** `string`
> > >
> > > 도시나 주소 같은 위치 레이블입니다. 위치에 레이블이 없으면 없습니다.
> > >
> > > **radius** `number` *required*
> > >
> > > `distance_unit` 단위의 중심점 주변 반경입니다.
> >
> > **regions** `string[]` *required*
> >
> > `US-CA` 같은 ISO 3166-2 코드로 나타낸 미국 주 및 DC입니다. 미국 영토(`PR`, `GU`, `VI`, `AS`, `MP`)와 미국 외 모든 지역은 `countries`를 통해 타기팅합니다.
> >
> > **zips** `string[]` *required*
> >
> > `US:78756`처럼 `COUNTRY:CODE` 형식을 키로 하는 ZIP 및 우편번호입니다.

**result\_event** `string | null` *required*

귀속된 횟수가 결과를 나타내는 Whop 픽셀 전환 이벤트입니다. 최적화 목표이거나, 광고 그룹별로 예산을 설정하는 캠페인의 경우 귀속된 횟수가 가장 많은 이벤트입니다. 목표가 Whop에 귀속되는 이벤트가 아니면 null입니다.

사용 가능한 옵션: `purchase`, `lead`, `schedule`, `submit_application`, `contact`, `complete_registration`, `view_content`, `add_to_cart`, `custom`, `messaging_conversation`

**result\_event\_name** `string | null` *required*

result\_event가 custom일 때의 판매자 정의 이벤트 이름입니다. 표준 이벤트에서는 null입니다.

**results** `number | null` *required*

result\_event의 기반이 되는 Whop 픽셀 귀속 횟수입니다. 캠페인의 광고 그룹들이 서로 다른 목표를 최적화하면 단일 result\_event가 없으며(null), 이 값은 대신 각 광고 그룹의 귀속 결과를 합산한 값입니다. Whop에 귀속될 수 있는 항목을 최적화하지 않으면 null입니다.

**return\_on\_ad\_spend** `number` *required*

구매 가치를 지출로 나눈 값으로, 둘 다 USD 기준입니다(통화 중립적인 비율). 지출이 없으면 0입니다.

**schedule\_value** `number` *required*

일정 예약 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**schedules** `number` *required*

Whop 픽셀에 귀속된 일정 예약 이벤트 수(라스트 클릭 기준)입니다.

**spend** `number` *required*

spend\_currency로 표시된 청구 금액입니다.

**spend\_currency** `string | null` *required*

모든 금액 지표의 ISO 4217 통화 코드입니다.

**starts\_at** `string | null` *required*

광고 그룹 게재가 시작되는 시각(ISO 8601 타임스탬프)입니다. 활성화되는 즉시 시작되면 `null`입니다.

**status** `string` *required*

광고 그룹의 활성화 여부입니다. `active`와 `paused`는 사용자가 설정하며, `rejected`는 광고 검토를 통과하지 못했음을 의미하고, `duplicating`은 아직 내용이 채워지고 있는 복사본입니다.

사용 가능한 옵션: `active`, `paused`, `rejected`, `duplicating`

**submitted\_application\_value** `number` *required*

신청서 제출 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**submitted\_applications** `number` *required*

Whop 픽셀에 귀속된 신청서 제출 이벤트 수(라스트 클릭 기준)입니다.

**title** `string | null` *required*

광고 그룹의 표시 이름입니다.

**unique\_click\_through\_rate** `number | null` *required*

고유 클릭 수를 노출 수로 나눈 값으로, 0과 1 사이입니다.

**unique\_clicks** `number` *required*

Whop 픽셀이 보고한 클릭한 사람 수로, 사람당 한 번만 집계됩니다.

**updated\_at** `string` *required*

광고 그룹이 마지막으로 업데이트된 시각(ISO 8601 타임스탬프)입니다.

**viewed\_content\_value** `number` *required*

콘텐츠 조회 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**viewed\_contents** `number` *required*

Whop 픽셀에 귀속된 콘텐츠 조회 이벤트 수(라스트 클릭 기준)입니다.

```json AdGroup theme={null}
{
	"id": "adgrp_xxxxxxxxxxx",
	"ad_campaign": {
		"id": "adcamp_xxxxxxxxxx"
	},
	"added_to_cart_value": 1050,
	"added_to_carts": 24,
	"audiences": {
		"exclude": [],
		"include": ["adaud_xxxxxxxxxxx"]
	},
	"bid_type": "minimum_cost",
	"budget_amount": 100,
	"budget_amount_local": 100,
	"budget_currency": "usd",
	"budget_type": "daily",
	"click_through_rate": 0.036,
	"clicks": 720,
	"completed_registration_value": 0,
	"completed_registrations": 16,
	"contact_value": 0,
	"contacts": 10,
	"conversion_event": "purchase",
	"cost_per_added_to_cart": 8.33,
	"cost_per_click": 0.28,
	"cost_per_completed_registration": 12.5,
	"cost_per_contact": 20,
	"cost_per_lead": 13.33,
	"cost_per_mille": 10,
	"cost_per_purchase": 25,
	"cost_per_result": 25,
	"cost_per_schedule": null,
	"cost_per_submitted_application": null,
	"cost_per_unique_click": 0.33,
	"cost_per_viewed_content": 0.67,
	"created_at": "2026-06-01T12:00:00Z",
	"custom_conversions": 5,
	"custom_event_counts": {
		"QualifiedCall": 4,
		"BookedDemo": 1
	},
	"custom_event_values": {
		"QualifiedCall": 2000,
		"BookedDemo": 0
	},
	"delivery_status": "issues",
	"learning_progress": null,
	"demographics": {
		"automatic": false,
		"minimum_age": 21,
		"maximum_age": 45,
		"gender": "all"
	},
	"delivery_schedule": {
		"monday": [
			{
				"start": "09:00",
				"end": "17:00"
			}
		],
		"tuesday": [
			{
				"start": "09:00",
				"end": "17:00"
			}
		],
		"wednesday": [
			{
				"start": "09:00",
				"end": "17:00"
			}
		],
		"thursday": [
			{
				"start": "09:00",
				"end": "17:00"
			}
		],
		"friday": [
			{
				"start": "09:00",
				"end": "12:00"
			},
			{
				"start": "16:00",
				"end": "20:00"
			}
		],
		"saturday": [
			{
				"start": "10:00",
				"end": "14:00"
			}
		],
		"sunday": [
			{
				"start": "12:00",
				"end": "16:00"
			}
		]
	},
	"desired_cost_per_result": 30,
	"devices": {
		"platforms": ["mobile", "desktop"],
		"operating_systems": [
			{
				"os": "ios",
				"minimum_version": "18.0"
			}
		]
	},
	"ends_at": "2026-07-01T12:00:00Z",
	"frequency": 1.6,
	"impressions": 20000,
	"issues": [
		{
			"id": "adiss_xxxxxxxxxxx",
			"category": "error",
			"title": "Ad issue",
			"message": "The audience is too narrow to deliver. Broaden the targeting to reach more people.",
			"resource_id": "adgrp_xxxxxxxxxxx",
			"resource_type": "ad_group"
		}
	],
	"languages": ["en"],
	"lead_value": 750,
	"leads": 15,
	"link_clicks": 576,
	"purchase_value": 5200,
	"purchases": 8,
	"reach": 12500,
	"regions": {
		"include": {
			"countries": ["US"],
			"country_groups": [],
			"regions": ["US-CA"],
			"cities": [
				{
					"key": "2418779",
					"name": "Miami"
				}
			],
			"zips": [],
			"custom_locations": [
				{
					"latitude": 30.2672,
					"longitude": -97.7431,
					"radius": 10,
					"distance_unit": "mile",
					"name": "Austin, TX"
				}
			]
		},
		"exclude": {
			"countries": [],
			"country_groups": [],
			"regions": [],
			"cities": [
				{
					"key": "2421215",
					"name": "Anchorage"
				}
			],
			"zips": [],
			"custom_locations": [
				{
					"latitude": 40.758,
					"longitude": -73.9855,
					"radius": 2,
					"distance_unit": "mile",
					"name": "Times Square"
				}
			]
		}
	},
	"result_event": "purchase",
	"result_event_name": null,
	"results": 8,
	"return_on_ad_spend": 26,
	"schedule_value": 0,
	"schedules": 0,
	"spend": 200,
	"spend_currency": "usd",
	"starts_at": "2026-06-01T12:00:00Z",
	"status": "active",
	"submitted_application_value": 0,
	"submitted_applications": 0,
	"title": "US founders",
	"unique_click_through_rate": 0.03,
	"unique_clicks": 600,
	"updated_at": "2026-06-02T12:00:00Z",
	"viewed_content_value": 0,
	"viewed_contents": 300
}
```
