> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# list_accounts

> list_accounts は認証済みエージェントが操作できるすべての広告主アカウントを AdCP ベンダーエージェントから返します。メディアバイ、シグナル、ガバナンス、クリエイティブの各プロトコルで機能します。

認証済みエージェントがこのベンダーエージェントで操作できるすべてのアカウントを返します。既存アカウントの探索、保留中アカウントのステータス変更確認、プロトコル操作で使用する `account_id` 値の取得に使用します。

上流管理のアカウント名前空間では、`list_accounts` は任意のディスカバリーの飾りではなく、名前空間ディスカバリー契約です。上流プラットフォームがアクセス可能なアカウントセットを所有するため、バイヤーは最初のアカウントスコープリクエストの前に明示的な `account_id` を解決しなければなりません（MUST）。認証済みクレデンシャルが複数のアカウントにアクセスできる場合、セラーは `list_accounts` を公開しなければなりません（MUST）。正確に 1 つのアカウントにアクセスできる場合、SDK が自動選択して必須アカウント呼び出しで `{ "account_id": "..." }` を送れるよう、セラーはそのシングルトンを返す `list_accounts` を公開すべきです（SHOULD）。`sync_accounts` プロビジョニングは、将来の明示的なケイパビリティがそのモードを宣言しない限り、3.0.x でアカウント ID アカウントを作成しません。今日これらのセラーで `sync_accounts` が公開されている場合、それは `account_id` ですでに識別されたアカウントに対する設定更新にのみ使用します。

`list_accounts` はすべてのベンダープロトコルで機能する — メディアバイエージェント、シグナルエージェント、ガバナンスエージェント、クリエイティブエージェントはすべてこの同じタスクを通じてアカウントを返します。

**応答時間**: 約1秒。

**リクエストスキーマ**: [`static/schemas/source/account/list-accounts-request.json`](https://github.com/adcontextprotocol/adcp/blob/main/static/schemas/source/account/list-accounts-request.json)
**レスポンススキーマ**: [`/schemas/v3/account/list-accounts-response.json`](https://adcontextprotocol.org/schemas/v3/account/list-accounts-response.json)

## クイックスタート

このエージェントが操作できるすべてのアカウントを一覧表示します。

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { testAgent } from "@adcp/sdk/testing";
  import { ListAccountsResponseSchema } from "@adcp/sdk";

  const result = await testAgent.listAccounts({});

  if (!result.success) {
    throw new Error(`Request failed: ${result.error}`);
  }

  const validated = ListAccountsResponseSchema.parse(result.data);

  if ("errors" in validated && validated.errors) {
    throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
  }

  for (const account of validated.accounts) {
    console.log(`${account.account_id}: ${account.name} (${account.status})`);
  }
  ```

  ```python Python theme={null}
  import asyncio
  from adcp.testing import test_agent

  async def main():
      result = await test_agent.simple.list_accounts()

      if hasattr(result, 'errors') and result.errors:
          raise Exception(f"Operation failed: {result.errors}")

      for account in result.accounts:
          print(f"{account.account_id}: {account.name} ({account.status})")

  asyncio.run(main())
  ```
</CodeGroup>

## リクエストパラメーター

すべてのパラメーターはオプション。空のリクエストは、認証済み呼び出し元に見えるすべてのアカウントを返します。既知の 1 アカウントを `account_id` または自然キー（`brand` + `operator`、オプションで `sandbox`）で再読み取りするときは `account` を使います。

| パラメーター       | 型       | 必須 | 説明                                                                                                                                                         |
| ------------ | ------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account`    | object  | No | 正確なアカウントフィルタ。ディスカバリー後に `{ "account_id": "..." }` を渡すか、バイヤー宣言アカウントセラーでは `brand`、`operator`、オプションの `sandbox` を持つ自然キーを渡します。セラーは認証済み呼び出し元に見える一致するアカウントのみを返します。 |
| `status`     | string  | No | アカウントステータスでフィルタ: `active`、`pending_approval`、`rejected`、`payment_required`、`suspended`、`closed`。                                                           |
| `sandbox`    | boolean | No | true の場合、サンドボックスアカウントのみ返します。false の場合、本番アカウントのみ返します。両方を返すには省略します。主にアカウント ID 名前空間で使用し、サンドボックスアカウントはプラットフォーム上の既存テストアカウントです。                                  |
| `pagination` | object  | No | 大規模アカウントセット用のページネーションカーソル。                                                                                                                                 |

## レスポンス

| フィールド        | 説明                           |
| ------------ | ---------------------------- |
| `accounts`   | アカウントオブジェクトの配列（下記参照）         |
| `errors`     | リクエストが失敗した場合のエラー配列           |
| `pagination` | さらに結果がある場合の次ページのページネーションカーソル |

**各アカウントには以下が含まれます:**

| フィールド                  | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_id`           | ベンダーエージェントの識別子。プロトコルタスクに渡す: `create_media_buy`、`get_signals`、`activate_signal`、`report_usage` などの操作。`status: "rejected"` の場合は省略されることがあります。                                                                                                                                                                                                                                                                                                                                                                                                               |
| `name`                 | アカウントのベンダーエージェント表示名                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `brand`                | ブランド参照オブジェクト: `domain`（[ブランドレジストリ](/docs/brand-protocol/brand-json)のハウスドメイン）とオプションの `brand_id`（ハウス内のサブブランド）                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `operator`             | オペレータードメイン。常に存在 — ブランドが直接運営する場合、`operator` はブランドのドメインと同一。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `status`               | 現在のアカウント状態: `active`、`pending_approval`、`rejected`、`payment_required`、`suspended`、`closed`                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `billing`              | 有効な請求モデル: `operator` または `agent`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `account_scope`        | セラーがアカウントをスコープした方法: `operator`、`brand`、`operator_brand`、`agent`。[アカウントスコープ](/docs/building/by-layer/L2/accounts-and-agents#account-scope) を参照。                                                                                                                                                                                                                                                                                                                                                                                                           |
| `payment_terms`        | このアカウントで合意した支払い条件: `net_15`、`net_30`、`net_45`、`net_60`、`net_90`、`prepay`。アカウントがアクティブな場合、すべての請求書に対して拘束力を持ちます。                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `governance_agents`    | このアカウントに登録されたガバナンスエージェントのエンドポイント。[`sync_governance`](/docs/accounts/tasks/sync_governance) でガバナンスエージェントが設定されている場合に存在。                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `setup`                | `status: "pending_approval"` の場合に存在。セットアップ完了の `url` と必要な内容を説明する `message` を含みます。                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `authorization`        | オプション。このアカウントに対する呼び出しエージェントのスコープ付与 — `allowed_tasks`、`field_scopes`、`scope_name`、`read_only`。すべてのベンダーエージェントタイプ（media-buy、signals、governance、creative、brand）に適用 — Accounts Protocol の面は共有。スコープイントロスペクションをサポートするベンダーエージェントはこれを設定すべき（SHOULD）。`attestation_verifier` 標準スコープを主張する media-buy sales agent は設定しなければならない（MUST）。不在は、ベンダーエージェントがこのアカウントについてイントロスペクション可能なスコープを宣伝しないことを意味する。呼び出し元は不在からアクセスを推論してはならず（MUST NOT）、RBAC エラーコードによるエラー駆動ディスカバリーにフォールバックする。完全な形状とセマンティクスは [Caller authorization](/docs/accounts/overview#caller-authorization) を参照。           |
| `notification_configs` | [`sync_accounts`](/docs/accounts/tasks/sync_accounts#account-level-webhook-subscriptions) で登録されたアカウントレベルの Webhook サブスクライバー。各エントリは `subscriber_id`、`url`、`event_types[]`、`active` を運ぶ。アカウントに永続化されたサブスクライバーがある場合に存在。`subscriber_id` はアカウントスコープの論理キー。同じサブスクライバーを再登録するとそのサブスクライバーの設定を置き換える。`authentication.credentials` はすべてのエントリで省略（書き込み専用）。この面を使って、sync 後に何がアクティブかを検証し、複数サブスクライバーにわたるファンアウトを監査し、バイヤー側の期待とセラー側の永続状態のドリフトを検出する。これはアカウントライフサイクルフィードではない。アカウントステータスの変更はアカウントの `status` フィールドまたはワンショットの `sync_accounts.push_notification_config` 非同期結果チャネルから読む。 |

### 単一パブリッシャーのカーディナリティ

正確に 1 つのパブリッシャーエンティティを提供するセラーは、呼び出しプリンシパルに関わらず、そのエンティティを `list_accounts` レスポンスの唯一のアカウントとして返してもよい（MAY）。[`list-accounts-response.json`](https://github.com/adcontextprotocol/adcp/blob/main/static/schemas/source/account/list-accounts-response.json) の *"Direct advertiser with single account"* の例がこのケースの正準です — `pagination` エンベロープを全く持たない単一要素の `accounts[]`。

`pagination.has_more: true` を要求するページネーションコンフォーマンスは、次の場合には適用されません:

* `pagination` が完全に不在（正準の単一アカウント形状）、または
* `pagination.total_count` が存在し ≤ 1

ランナーはどちらの場合もページネーションウォークフェーズを `not_applicable` として採点すべきです（SHOULD）。このパターンはコンフォーマントです。スペックは `accounts[]` に `minItems` 制約を持たず、単一アカウントの例は規範的です。

## 一般的なシナリオ

### アカウントがアクティブになるまでポーリング

`sync_accounts` が `pending_approval` を返した後、アカウントが準備できるまでポーリングします。

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { testAgent } from "@adcp/sdk/testing";
  import { ListAccountsResponseSchema } from "@adcp/sdk";

  async function waitForAccount(targetAccountId, maxAttempts = 20) {
    for (let i = 0; i < maxAttempts; i++) {
      const result = await testAgent.listAccounts({ status: "active" });

      if (!result.success) {
        throw new Error(`Request failed: ${result.error}`);
      }

      const validated = ListAccountsResponseSchema.parse(result.data);

      if ("errors" in validated && validated.errors) {
        throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
      }

      if ("accounts" in validated) {
        const account = validated.accounts.find(a => a.account_id === targetAccountId);
        if (account) {
          console.log(`Account active: ${account.account_id}`);
          return account;
        }
      }

      // 再ポーリングまで30秒待機
      await new Promise(resolve => setTimeout(resolve, 30_000));
    }

    throw new Error(`Account ${targetAccountId} did not become active`);
  }
  ```

  ```python Python theme={null}
  import asyncio
  from adcp.testing import test_agent

  async def wait_for_account(target_account_id: str, max_attempts: int = 20):
      for _ in range(max_attempts):
          result = await test_agent.simple.list_accounts(status='active')

          if hasattr(result, 'errors') and result.errors:
              raise Exception(f"Operation failed: {result.errors}")

          account = next(
              (a for a in result.accounts if a.account_id == target_account_id),
              None
          )
          if account:
              print(f"Account active: {account.account_id}")
              return account

          await asyncio.sleep(30)

      raise Exception(f"Account {target_account_id} did not become active")
  ```
</CodeGroup>

### アクティブなアカウントのみフィルタ

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { testAgent } from "@adcp/sdk/testing";
  import { ListAccountsResponseSchema } from "@adcp/sdk";

  const result = await testAgent.listAccounts({ status: "active" });

  if (!result.success) {
    throw new Error(`Request failed: ${result.error}`);
  }

  const validated = ListAccountsResponseSchema.parse(result.data);

  if ("accounts" in validated) {
    for (const account of validated.accounts) {
      console.log(`${account.account_id}: ${account.name} — billing: ${account.billing}`);
    }
  }
  ```

  ```python Python theme={null}
  import asyncio
  from adcp.testing import test_agent

  async def main():
      result = await test_agent.simple.list_accounts(status='active')

      if hasattr(result, 'errors') and result.errors:
          raise Exception(f"Operation failed: {result.errors}")

      for account in result.accounts:
          print(f"{account.account_id}: {account.name} — billing: {account.billing}")

  asyncio.run(main())
  ```
</CodeGroup>

## エラーハンドリング

| エラーコード              | 説明                    | 解決策                               |
| ------------------- | --------------------- | --------------------------------- |
| `ACCOUNT_NOT_FOUND` | このエージェントのアカウントが見つからない | まず `sync_accounts` を実行して購買関係を確立する |

## 次のステップ

* [sync\_accounts](/docs/accounts/tasks/sync_accounts) — セラーと広告主アカウントを同期します
* [sync\_governance](/docs/accounts/tasks/sync_governance) — ガバナンスエージェントをアカウントに同期します
* [アカウントとエージェント](/docs/building/by-layer/L2/accounts-and-agents) — 請求モデル、信頼モデル、認可オペレーター
* [ブランドプロトコル](/docs/brand-protocol/brand-json) — ベンダーエージェントがブランドの `domain` からブランドアイデンティティを解決する方法