list_connected_accounts

General (Account Management) Write

List all connected ad accounts across platforms

Endpoint

POST https://api.adspirer.ai/api/v1/tools/list_connected_accounts/execute

Headers

Authorization: Bearer sk_live_... — your Adspirer API key (required)
Content-Type: application/json (required)
Idempotency-Key: <uuid> — recommended for write operations to make retries safe

Description

List all connected ad accounts across platforms.

Returns account IDs, names, and platforms for all active accounts. Use this at the start
of every conversation to know which accounts are available.

CRITICAL for multi-account users (agencies):
- Always call this first to discover available accounts
- Use the returned account IDs when calling any platform tool
- If user mentions a business name, match it to an account from this list

Returns for each account:
- platform: google_ads, meta_ads, tiktok_ads, linkedin_ads
- account_id: Platform account ID (pass to tools as customer_id/ad_account_id/advertiser_id/account_id)
- account_name: Display name
- account_tier: primary, secondary, or active
- status: connected, needs_reauth

Zero API calls — reads directly from database.

Request body

All tool arguments are wrapped in an arguments object.

Field	Type	Description
`platform`	`string` optional	Filter by platform: google_ads, meta_ads, tiktok_ads, or linkedin_ads. If not specified, returns accounts across all platforms.

Example request

{
  "arguments": {
    "platform": "string"
  }
}

Example responses

200 — Success

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for list_connected_accounts)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "list_connected_accounts"
}

400 — Tool-level error (bad arguments / multi-account selection)

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "list_connected_accounts"
}

402 — Quota exhausted

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "list_connected_accounts",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: General (Account Management) · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai