Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt

Use this file to discover all available pages before exploring further.

Returns all accounts the authenticated agent can operate on this vendor agent. Use this to discover existing accounts, check status changes on pending accounts, and retrieve account_id values for use in protocol operations. For upstream-managed account namespaces, list_accounts is not optional discovery polish; it is the namespace discovery contract. The upstream platform owns the accessible account set, so buyers MUST resolve an explicit account_id before the first account-scoped request. If the authenticated credential can access more than one account, the seller MUST expose list_accounts; if it can access exactly one account, the seller SHOULD expose list_accounts returning that singleton so SDKs can auto-select it and still send { "account_id": "..." } on required-account calls. sync_accounts provisioning does not create account-id accounts in 3.0.x unless a future explicit capability declares that mode; if sync_accounts is exposed on these sellers today, use it only for settings updates against an account already identified by account_id. list_accounts works across all vendor protocols — media buy agents, signals agents, governance agents, and creative agents all return accounts through this same task. Response Time: ~1s. Request Schema: static/schemas/source/account/list-accounts-request.json Response Schema: /schemas/v3/account/list-accounts-response.json

​
Quick Start

List all accounts this agent can operate: 
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})`);
}

​
Request Parameters

All parameters are optional. An empty request returns all accounts visible to the authenticated caller. Use account when re-reading one known account by account_id or by natural key (brand + operator, optionally sandbox).
ParameterTypeRequiredDescription
accountobjectNoExact account filter. Pass { "account_id": "..." } after discovery, or a natural key with brand, operator, and optional sandbox for buyer-declared account sellers. The seller returns only matching accounts visible to the authenticated caller.
statusstringNoFilter by account status: active, pending_approval, rejected, payment_required, suspended, or closed.
sandboxbooleanNoWhen true, return only sandbox accounts. When false, return only production accounts. Omit to return both. Primarily used with account-id namespaces where sandbox accounts are pre-existing test accounts on the platform.
paginationobjectNoPagination cursor for large account sets.

​
Response

FieldDescription
accountsArray of account objects (see below)
errorsArray of errors, if the request failed
paginationPagination cursor for the next page, if more results exist
Each account includes:
FieldDescription
account_idVendor agent’s identifier. Pass this to protocol tasks: create_media_buy, get_signals, activate_signal, report_usage, and other operations. May be absent when status: "rejected".
nameVendor agent’s display name for the account
brandBrand reference object: domain (the brand registry house domain) and optional brand_id (sub-brand within the house)
operatorOperator domain. Always present — when the brand operates directly, operator equals the brand’s domain.
statusCurrent account state: active, pending_approval, rejected, payment_required, suspended, or closed
billingBilling model in effect: operator or agent
account_scopeHow the seller scoped this account: operator, brand, operator_brand, or agent. See account scope.
payment_termsPayment terms agreed for this account: net_15, net_30, net_45, net_60, net_90, or prepay. Binding for all invoices when the account is active.
governance_agentsGovernance agent endpoints registered on this account. Present when governance agents have been configured via sync_governance.
setupPresent when status: "pending_approval". Contains url for completing setup and message explaining what’s needed.
authorizationOptional. The calling agent’s scope grant for this account — allowed_tasks, field_scopes, scope_name, read_only. Applies to every vendor agent type (media-buy, signals, governance, creative, brand) — the Accounts Protocol surface is shared. Vendor agents that support scope introspection SHOULD populate this; media-buy sales agents claiming the attestation_verifier standard scope MUST populate it. Absence means the vendor agent does not advertise introspectable scope for this account; callers MUST NOT infer access from absence and fall back to error-driven discovery via the RBAC error codes. See Caller authorization for the full shape and semantics.
notification_configsAccount-level webhook subscribers registered via sync_accounts. Each entry carries subscriber_id, url, event_types[], and active. Present when the account has any persisted subscribers. subscriber_id is the account-scoped logical key; re-registering the same subscriber replaces that subscriber’s config. authentication.credentials is omitted on every entry (write-only). Use this surface to verify what’s active after a sync, audit fan-out across multiple subscribers, and detect drift between buyer-side expectations and seller-side persisted state. This is not an account lifecycle feed; account status changes are read from the account’s status field or from the one-shot sync_accounts.push_notification_config async result channel.

​
Single-publisher cardinality

A seller serving exactly one publisher entity MAY return that entity as the sole account on list_accounts responses, regardless of calling principal. The “Direct advertiser with single account” example in list-accounts-response.json is canonical for this case — a single-element accounts[] with no pagination envelope at all. Pagination conformance requiring pagination.has_more: true does not apply when:
  • pagination is absent entirely (canonical single-account shape), or
  • pagination.total_count is present and ≤ 1
Runners SHOULD grade pagination-walk phases as not_applicable in either case. This pattern is conformant; the spec carries no minItems constraint on accounts[] and the single-account example is normative.

​
Common Scenarios

​
Poll until account becomes active

After sync_accounts returns pending_approval, poll until the account is ready: 
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;
      }
    }

    // Wait 30 seconds before polling again
    await new Promise(resolve => setTimeout(resolve, 30_000));
  }

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

​
Filter active accounts only

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}`);
  }
}

​
Error Handling

Error CodeDescriptionResolution
ACCOUNT_NOT_FOUNDNo accounts found for this agentRun sync_accounts first to establish a buying relationship

​
Next Steps