ターゲティング - Ad Control Help Center

ターゲティングには、広告主がキャンペーンを予約するときに選択するターゲティングオプションが含まれます。このページのエンドポイントでターゲティングを管理します。ターゲティング内のオプションを管理する方法は、ターゲティングオプションを参照してください。

読み取りエンドポイントにはcontext-targeting:readスコープ、書き込みエンドポイントにはcontext-targeting:writeスコープが必要です。事前準備を参照してください。
プロジェクトはAPIキーで決まるため、パスにプロジェクトIDは含まれません。
各エンドポイントには、そのエンドポイント固有のエラーのみを記載しています。すべてのエンドポイントに共通するエラーは、エラーコードを参照してください。

ターゲティングオブジェクト

一覧取得、取得、作成、名前変更のエンドポイントは、ターゲティングを次の形式で返します。削除エンドポイントは_idのみを返します。APIのフィールドでは、オプションをcategoriesと呼びます。

フィールド	タイプ	説明
`_id`	string	ターゲティングID（26文字のULID）。サーバーが生成します。
`name`	string	ターゲティング名
`categories`	object[]	オプショングループとその下位オプションを含む、ターゲティング内のすべてのオプション。各項目はオプションオブジェクトで、コンテキストIDの数（`contextCount`）は含みますが、コンテキストID自体は含みません。
`categoryCount`	number	下位オプションを含む、ターゲティング内のオプションの数。常に含まれます。
`syncedAt`	number	このターゲティングの広告配信への直近の読み込みが始まった時刻（エポックミリ秒）。この時刻以前に成功した変更は読み込み済みです。
`createdAt`	string	ターゲティングの作成日時（ISO 8601、UTC）
`updatedAt`	string	ターゲティングの最終更新日時（ISO 8601、UTC）。ターゲティングが広告配信に読み込まれたときにも変わります。

categoriesとsyncedAtは、すべてのレスポンスに含まれるわけではありません。

レスポンス	`categories`	`syncedAt`
ターゲティング一覧の取得、ターゲティングの取得	デフォルトで含まれます。`includeCategories=false`を指定すると省略されます。	値がある場合に含まれます
ターゲティングの作成、ターゲティングの一括作成	含まれます	新しいターゲティングはまだ読み込まれていないため、省略されます
ターゲティング名の変更、ターゲティング名の一括変更	省略されます	値がある場合に含まれます

syncedAtは、ターゲティングの最初の読み込みが完了するまで省略されます。コンテキストIDの変更、オプションの追加、オプションの移動や切り離しを行った後も、通常は次の読み込みが完了するまで省略されます。

変更が読み込まれたかどうかは、変更が成功した時刻とsyncedAtを比べて確認してください。syncedAtの有無では判断しないでください。変更が反映されるタイミングを参照してください。

ターゲティング一覧の取得

プロジェクト内のすべてのコンテキストターゲティングを返します。オーディエンスターゲティングは含まれず、一覧はページ分割されません。

リクエスト

GET /context-targeting

context-targeting:readスコープが必要です。

クエリパラメータ

パラメータ	タイプ	必須	デフォルト	説明
`includeCategories`	boolean	-	`true`	`categories`を含めるかどうか。`false`を指定すると`categories`は省略されますが、`categoryCount`でオプションの数は引き続き確認できます。オプションが多いターゲティングでは`false`を指定し、オプション一覧の取得でオプションをページ単位で取得してください。`true`と`false`以外の値を指定すると`400`が返されます。

リクエスト例

curl "https://lake.adrop.io/context-targeting?includeCategories=false" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

レスポンス例

200で、ターゲティングオブジェクトの配列を返します。

[
  {
    "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
    "name": "News Sections",
    "categoryCount": 2,
    "syncedAt": 1791854650000,
    "createdAt": "2026-10-13T01:23:45.000Z",
    "updatedAt": "2026-10-13T01:24:12.000Z"
  }
]

ターゲティングの取得

コンテキストターゲティングを1件返します。

リクエスト

GET /context-targeting/{targetingId}

context-targeting:readスコープが必要です。

パスパラメータ

パラメータ	タイプ	必須	説明
`targetingId`	string	O	ターゲティングID

クエリパラメータ

パラメータ	タイプ	必須	デフォルト	説明
`includeCategories`	boolean	-	`true`	`categories`を含めるかどうか。`false`を指定すると`categories`は省略されますが、`categoryCount`でオプションの数は引き続き確認できます。`true`と`false`以外の値を指定すると`400`が返されます。

リクエスト例

curl "https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

レスポンス例

200で、ターゲティングオブジェクトを返します。

{
  "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
  "name": "News Sections",
  "categories": [
    {
      "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
      "name": "Sports",
      "type": "atomic",
      "contextCount": 3,
      "createdAt": "2026-10-13T01:23:45.000Z",
      "updatedAt": "2026-10-13T01:23:45.000Z"
    },
    {
      "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9",
      "name": "Tech",
      "type": "atomic",
      "contextCount": 3,
      "createdAt": "2026-10-13T01:23:45.000Z",
      "updatedAt": "2026-10-13T01:23:45.000Z"
    }
  ],
  "categoryCount": 2,
  "syncedAt": 1791854650000,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:24:12.000Z"
}

オプションのコンテキストIDを取得するには、オプションの取得を使用してください。 エラー

ステータス	`errorCode`	発生条件
404	`TARGETING_NOT_FOUND`	プロジェクトに、このIDのコンテキストターゲティングがありません。オーディエンスターゲティングのIDを指定した場合も、このエラーが返されます。

ターゲティングの作成

コンテキストターゲティングを作成します。同じリクエストでオプションも作成できます。

リクエスト

POST /context-targeting

context-targeting:writeスコープが必要です。

リクエストボディ

フィールド	タイプ	必須	デフォルト	説明
`name`	string	O	—	ターゲティング名（2〜36文字）。オーディエンスターゲティングを含む、プロジェクト内のすべてのターゲティングの中で一意である必要があります。名前のルールを参照してください。
`categories`	object[]	-	—	ターゲティングと一緒に作成するオプション。下位オプションを含めて、1回のリクエストで最大100個です。

categoriesの各項目には、次のフィールドを指定します。

フィールド	タイプ	必須	デフォルト	説明
`name`	string	O	—	オプション名（2〜36文字）。オプショングループと下位オプションを含め、ターゲティング内で一意である必要があります。
`contexts`	string[]	-	—	オプションのコンテキストID。オプショングループの場合は、オプショングループ自身のコンテキストIDです。コンテキストIDのルールを参照してください。
`type`	string	-	説明を参照	`atomic`（通常のオプション）または`collection`。省略すると、`children`がある場合は空の配列であってもオプショングループになり、それ以外の場合は`atomic`になります。
`children`	object[]	-	—	オプショングループのみ。作成する下位オプションで、各項目に`name`（必須）と`contexts`を指定します。
`exposeChildren`	boolean	-	`false`	オプショングループのみ。下位オプションを広告主に表示するかどうか。下位オプションを広告主に表示を参照してください。

1回のリクエストに含められるコンテキストIDは、下位オプションの分を含めて合計10,000個までです。
IDはすべてサーバーが生成します。_idを含むリクエストは400で失敗します。
categoriesの項目にはparentを指定できません。指定したリクエストは400で失敗します。既存のオプショングループにオプションを追加する方法は、オプショングループへのオプション追加を参照してください。
100個を超えるオプションを作成するには、まずターゲティングを作成してから、オプションの一括追加を使用してください。

オプショングループの仕組みについては、オプショングループの作成を参照してください。

リクエスト例

curl -X POST https://lake.adrop.io/context-targeting \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "News Sections",
    "categories": [
      { "name": "Sports", "contexts": ["sport", "baseball", "soccer"] },
      { "name": "Tech", "contexts": ["tech", "ai", "mobile"] }
    ]
  }'

レスポンス例

201で、オプションを含む新しいターゲティングオブジェクトを返します。

{
  "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
  "name": "News Sections",
  "categories": [
    {
      "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
      "name": "Sports",
      "type": "atomic",
      "contextCount": 3,
      "createdAt": "2026-10-13T01:23:45.000Z",
      "updatedAt": "2026-10-13T01:23:45.000Z"
    },
    {
      "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9",
      "name": "Tech",
      "type": "atomic",
      "contextCount": 3,
      "createdAt": "2026-10-13T01:23:45.000Z",
      "updatedAt": "2026-10-13T01:23:45.000Z"
    }
  ],
  "categoryCount": 2,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:23:45.000Z"
}

ターゲティングと各オプションの_idを保存してください。後でターゲティングを変更するときに必要です。 エラー

ステータス	`errorCode`	発生条件
409	`TARGETING_NAME_DUPLICATE`	プロジェクトに、`name`と同じ名前のターゲティングがすでにあります。そのターゲティングがコンテキストターゲティングの場合は、`detail.existingId`にそのIDが入ります。それ以外の場合は、`detail`が省略されます。
409	`TARGETING_CATEGORY_NAME_DUPLICATE`	`categories`内の2つのオプション（下位オプションを含む）が同じ名前です。
400	`TARGETING_CATEGORY_NOT_SUPPORTED`	オプションのフィールドがそのタイプと合っていません。たとえば、オプショングループに下位オプションも自身のコンテキストIDもない場合、`type: "atomic"`で`children`を送った場合、通常のオプションに`exposeChildren`を送った場合です。ターゲティングは作成されません。
400	`TARGETING_CONTEXT_LIMIT_EXCEEDED`	プロジェクト全体のコンテキストIDの数が上限を超えます。上限を参照してください。
400	`TARGETING_COLLECTION_CONTEXT_DUPLICATED`	オプショングループ自身のコンテキストIDが、プロジェクト内または同じリクエスト内の別のオプショングループでも、そのオプショングループ自身のコンテキストIDとしてすでに使われています。`detail.conflicts`に重複の一覧が入ります。制約事項を参照してください。

名前がすでに使われている場合のレスポンスは次のとおりです。

{
  "statusCode": 409,
  "errorCode": "TARGETING_NAME_DUPLICATE",
  "detail": {
    "existingId": "01JAB3XK5Q8V7M2N4P6R9T0W1Y"
  }
}

作成は冪等ではありません。作成リクエストがタイムアウトした場合や5xxエラーで失敗した場合は、再送できます。最初のリクエストが成功していた場合、再送したリクエストは409 TARGETING_NAME_DUPLICATEで失敗し、detail.existingIdには最初のリクエストで作成されたターゲティングのIDが入ります。再試行と重複リクエストを参照してください。

ターゲティング名の変更

ターゲティングの名前を変更します。オプションとコンテキストIDは変更されません。

リクエスト

PATCH /context-targeting/{targetingId}

context-targeting:writeスコープが必要です。

パスパラメータ

パラメータ	タイプ	必須	説明
`targetingId`	string	O	ターゲティングID

リクエストボディ

フィールド	タイプ	必須	説明
`name`	string	O	新しいターゲティング名（2〜36文字）。オーディエンスターゲティングを含む、プロジェクト内のすべてのターゲティングの中で一意である必要があります。現在の名前をそのまま送ることもできます。名前のルールを参照してください。

リクエスト例

curl -X PATCH https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Article Sections" }'

レスポンス例

200で、名前を変更したターゲティングオブジェクトをcategoriesなしで返します。オプションを取得するには、ターゲティングの取得またはオプション一覧の取得を使用してください。

{
  "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
  "name": "Article Sections",
  "categoryCount": 2,
  "syncedAt": 1791854650000,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T02:10:00.000Z"
}

エラー

ステータス	`errorCode`	発生条件
404	`TARGETING_NOT_FOUND`	プロジェクトに、このIDのコンテキストターゲティングがありません。
409	`TARGETING_NAME_DUPLICATE`	プロジェクトに、`name`と同じ名前の別のターゲティングがすでにあります。そのターゲティングがコンテキストターゲティングの場合は、`detail.existingId`にそのIDが入ります。

ターゲティングの削除

ターゲティングと、そのすべてのオプション（オプショングループと下位オプションを含む）を削除します。

承認済みで終了していないキャンペーンが、ターゲティングのいずれかのオプションを含めている、または除外している間は、そのターゲティングを削除できません。リクエストは400 TARGETING_LOCKEDで失敗し、何も削除されません。個々のオプションの削除は、この制限を受けません。オプションの削除を参照してください。

リクエスト

DELETE /context-targeting/{targetingId}

context-targeting:writeスコープが必要です。

パスパラメータ

パラメータ	タイプ	必須	説明
`targetingId`	string	O	削除するターゲティングのID

リクエスト例

curl -X DELETE https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

レスポンス例

200で、削除したターゲティングのIDのみを返します。

{
  "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y"
}

エラー

ステータス	`errorCode`	発生条件
404	`TARGETING_NOT_FOUND`	プロジェクトに、このIDのコンテキストターゲティングがありません。成功した削除リクエストを再送した場合は、ターゲティングはすでに削除されています。
400	`TARGETING_LOCKED`	承認済みで終了していないキャンペーンが、ターゲティングのいずれかのオプションを含めている、または除外しています。

一括操作

1回のリクエストで、最大100件のターゲティングを作成、名前変更、削除できます。

まず、リクエスト全体が検査されます。検査の対象は、項目数（1〜100件）、各フィールドの形式、リクエストあたりの合計です。検査に失敗すると、リクエスト全体が400で失敗し、何も反映されません。
プロジェクトで別のAPI書き込みを処理中の場合、リクエスト全体が409 CONTEXT_TARGETING_WRITE_IN_PROGRESSで失敗し、何も反映されないことがあります。同時書き込みを参照してください。
それ以外の場合、すべての項目が失敗したときでも、レスポンスは200で、項目ごとの結果が含まれます。一部の項目が成功し、ほかの項目が失敗することもあるため、項目ごとにsuccessを確認してください。

フィールド	タイプ	説明
`results`	object[]	項目ごとの結果（リクエストの順序どおり）
`results[].index`	number	リクエストの`items`または`ids`における項目の位置（0から始まる）
`results[].success`	boolean	項目が成功したかどうか
`results[].data`	object	成功した項目の結果。失敗した項目では省略されます。
`results[].error`	object	失敗した項目のエラー。`statusCode`、`errorCode`と、一部のエラーでは`detail`が含まれます。成功した項目では省略されます。
`succeeded`	number	成功した項目の数
`failed`	number	失敗した項目の数

作成と削除のリクエストでは、検査を通過した項目がまとめて反映されます。予期しないエラーが発生した場合は、リクエストの内容は何も反映されません。このとき、検査で失敗した項目にはそのエラーが返され、それ以外の項目は500 UNCATCHEDで失敗します。同じリクエストを再送してください。名前変更のリクエストでは、各項目がリクエストの順序どおりに1件ずつ反映されます。詳しくは一括操作のレスポンスを参照してください。

ターゲティングの一括作成

オプションの有無にかかわらず、最大100件のターゲティングを作成します。

リクエスト

POST /context-targeting/bulk/create

context-targeting:writeスコープが必要です。

リクエストボディ

フィールド	タイプ	必須	説明
`items`	object[]	O	作成するターゲティング（1〜100件）。各項目には、ターゲティングの作成のリクエストボディと同じフィールドを指定します。

すべての項目を合わせて、1回のリクエストに含められるオプションは下位オプションを含めて100個まで、コンテキストIDは10,000個までです。

リクエスト例

curl -X POST https://lake.adrop.io/context-targeting/bulk/create \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "name": "Video Sections",
        "categories": [
          { "name": "Highlights", "contexts": ["highlight", "replay"] }
        ]
      },
      {
        "name": "Podcast Sections",
        "categories": [
          { "name": "Interviews", "contexts": ["interview", "talk"] }
        ]
      },
      { "name": "News Sections" }
    ]
  }'

レスポンス例

成功した項目のdataは、オプションを含む新しいターゲティングオブジェクトです。この例では、「News Sections」という名前のターゲティングがすでにあるため、3番目の項目が失敗します。

{
  "results": [
    {
      "index": 0,
      "success": true,
      "data": {
        "_id": "01JAB3XK5WE1F2G3H4J5K6M7N8",
        "name": "Video Sections",
        "categories": [
          {
            "_id": "01JAB3XK5XF1G2H3J4K5M6N7P8",
            "name": "Highlights",
            "type": "atomic",
            "contextCount": 2,
            "createdAt": "2026-10-13T02:20:00.000Z",
            "updatedAt": "2026-10-13T02:20:00.000Z"
          }
        ],
        "categoryCount": 1,
        "createdAt": "2026-10-13T02:20:00.000Z",
        "updatedAt": "2026-10-13T02:20:00.000Z"
      }
    },
    {
      "index": 1,
      "success": true,
      "data": {
        "_id": "01JAB3XK5WE1F2G3H4J5K6M7N9",
        "name": "Podcast Sections",
        "categories": [
          {
            "_id": "01JAB3XK5XF1G2H3J4K5M6N7P9",
            "name": "Interviews",
            "type": "atomic",
            "contextCount": 2,
            "createdAt": "2026-10-13T02:20:00.000Z",
            "updatedAt": "2026-10-13T02:20:00.000Z"
          }
        ],
        "categoryCount": 1,
        "createdAt": "2026-10-13T02:20:00.000Z",
        "updatedAt": "2026-10-13T02:20:00.000Z"
      }
    },
    {
      "index": 2,
      "success": false,
      "error": {
        "statusCode": 409,
        "errorCode": "TARGETING_NAME_DUPLICATE",
        "detail": {
          "existingId": "01JAB3XK5Q8V7M2N4P6R9T0W1Y"
        }
      }
    }
  ],
  "succeeded": 2,
  "failed": 1
}

各項目は、ターゲティングの作成と同じエラーで失敗します。同じリクエスト内の前の項目で作成したターゲティングと名前が重複した場合、TARGETING_NAME_DUPLICATEにはdetail.existingIdの代わりに、その項目のインデックスを示すdetail.duplicateOfIndexが入ります。

ターゲティング名の一括変更

最大100件のターゲティングの名前を変更します。

リクエスト

POST /context-targeting/bulk/update

context-targeting:writeスコープが必要です。

リクエストボディ

フィールド	タイプ	必須	説明
`items`	object[]	O	名前を変更するターゲティング（1〜100件）
`items[]._id`	string	O	ターゲティングID
`items[].name`	string	O	新しいターゲティング名。ターゲティング名の変更と同じルールが適用されます。

リクエスト例

curl -X POST https://lake.adrop.io/context-targeting/bulk/update \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y", "name": "Article Sections" }
    ]
  }'

レスポンス例

成功した項目のdataは、名前を変更したターゲティングオブジェクトで、categoriesは含まれません。

{
  "results": [
    {
      "index": 0,
      "success": true,
      "data": {
        "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
        "name": "Article Sections",
        "categoryCount": 2,
        "syncedAt": 1791854650000,
        "createdAt": "2026-10-13T01:23:45.000Z",
        "updatedAt": "2026-10-13T02:10:00.000Z"
      }
    }
  ],
  "succeeded": 1,
  "failed": 0
}

各項目は、ターゲティング名の変更と同じエラーで失敗します。

ターゲティングの一括削除

最大100件のターゲティングと、それぞれのすべてのオプションを削除します。

リクエスト

POST /context-targeting/bulk/delete

context-targeting:writeスコープが必要です。

リクエストボディ

フィールド	タイプ	必須	説明
`ids`	string[]	O	削除するターゲティングのID（1〜100件）

リクエスト例

curl -X POST https://lake.adrop.io/context-targeting/bulk/delete \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["01JAB3XK5Q8V7M2N4P6R9T0W1Y"]
  }'

レスポンス例

成功した項目のdataには、削除したターゲティングの_idのみが含まれます。この例では、承認済みで終了していないキャンペーンがターゲティングのオプションの1つを含めているため、ターゲティングは削除されません。

{
  "results": [
    {
      "index": 0,
      "success": false,
      "error": {
        "statusCode": 400,
        "errorCode": "TARGETING_LOCKED"
      }
    }
  ],
  "succeeded": 0,
  "failed": 1
}

各項目は、ターゲティングの削除と同じエラーで失敗します。

​ターゲティングオブジェクト

​ターゲティング一覧の取得

​リクエスト

​クエリパラメータ

​リクエスト例

​レスポンス例

​ターゲティングの取得

​リクエスト

​パスパラメータ

​クエリパラメータ

​リクエスト例

​レスポンス例

​ターゲティングの作成

​リクエスト

​リクエストボディ

​リクエスト例

​レスポンス例

​ターゲティング名の変更

​リクエスト

​パスパラメータ

​リクエストボディ

​リクエスト例

​レスポンス例

​ターゲティングの削除

​リクエスト

​パスパラメータ

​リクエスト例

​レスポンス例

​一括操作

​ターゲティングの一括作成

​リクエスト

​リクエストボディ

​リクエスト例

​レスポンス例

​ターゲティング名の一括変更

​リクエスト

​リクエストボディ

​リクエスト例

​レスポンス例

​ターゲティングの一括削除

​リクエスト

​リクエストボディ

​リクエスト例

​レスポンス例

ターゲティングオブジェクト

ターゲティング一覧の取得

リクエスト

クエリパラメータ

リクエスト例

レスポンス例

ターゲティングの取得

リクエスト

パスパラメータ

クエリパラメータ

リクエスト例

レスポンス例

ターゲティングの作成

リクエスト

リクエストボディ

リクエスト例

レスポンス例

ターゲティング名の変更

リクエスト

パスパラメータ

リクエストボディ

リクエスト例

レスポンス例

ターゲティングの削除

リクエスト

パスパラメータ

リクエスト例

レスポンス例

一括操作

ターゲティングの一括作成

リクエスト

リクエストボディ

リクエスト例

レスポンス例

ターゲティング名の一括変更

リクエスト

リクエストボディ

リクエスト例

レスポンス例

ターゲティングの一括削除

リクエスト

リクエストボディ

リクエスト例

レスポンス例