API Reference › Meta Ads › list_meta_promotable_apps

list_meta_promotable_apps

Meta Ads Read

User wants to run a Meta app-install / app-promotion campaign, or asks which mobile apps they can advertise

Endpoint

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

Headers

Description

User wants to run a Meta app-install / app-promotion campaign, or asks which mobile apps they can advertise. Returns the apps this ad account is allowed to promote, each with its numeric Facebook App ID and the App Store / Google Play URLs Meta already holds. ALWAYS call this BEFORE creating an OUTCOME_APP_PROMOTION campaign. The `app_id` Meta requires is the numeric FACEBOOK App ID — NOT an iOS bundle ID (com.example.app) or Android package name. Customers routinely guess it wrong and the campaign fails. Workflow: 1. Call this tool to discover promotable apps 2. Pass the returned `app_id` + matching `app_store_url` to a campaign creation tool with objective OUTCOME_APP_PROMOTION 3. OS targeting is derived from the store URL automatically — Meta rejects an ad set whose OS targeting disagrees with the promoted app When to use: - Before ANY app campaign creation (app_id + app_store_url are both required) - When the user asks "which apps can I advertise?" - When an app campaign failed with a promoted-object, app-setup, or "Mobile Targeting Mismatch" error Apps that have no App Store / Google Play listing are returned separately with an explanation — Meta cannot run an app campaign for a web-only or canvas app.

Request body

All tool arguments are wrapped in an arguments object.

FieldTypeDescription
ad_account_idstring optionalMeta ad account ID (e.g., 'act_123456'). If not provided, uses the connected account.

Example request

{
  "arguments": {
    "ad_account_id": "string"
  }
}

Example responses

200 — Success

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

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_meta_promotable_apps"
}

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_meta_promotable_apps",
  "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: Meta Ads · All tools

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