List Meta Campaigns

User wants to see their existing Meta/Facebook/Instagram campaigns, browse campaign structure, or find a campaign ID.

This tool retrieves all campaigns in the connected Meta ad account with their status, objective, budget, and creation date.

Returns:

Campaign list with name, ID, status, objective, budget
Status summary (how many ACTIVE, PAUSED, etc.)
Next step guidance for drilling into campaign details

When to use this tool:

“Show me my Meta campaigns”
“List my Facebook ad campaigns”
“What campaigns do I have running?”
“Which campaigns are active?”
“Find my campaign for [product/brand]”
“I need to find a campaign ID”
Before using update/pause/resume tools when user doesn’t know the campaign ID

Parameters:

status: Filter by status (comma-separated: ‘ACTIVE’, ‘PAUSED’, ‘DELETED’, ‘ARCHIVED’)
effective_status: Filter by effective status (includes inherited states like ‘CAMPAIGN_PAUSED’)
objective: Filter by objective (OUTCOME_TRAFFIC, OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_AWARENESS)
limit: Max campaigns to return (default: 100)
ad_account_id: Required for multi-account users. Get from list_connected_accounts

Execution time: 2-5 seconds Data source: Meta Marketing API (live)

Workflow:

Use list_meta_campaigns to find campaigns
Use get_meta_campaign_details with a campaign ID to see full structure
Use update_meta_campaign or update_meta_ad_set to make changes

POST

api

tools

list_meta_campaigns

execute

List Meta Campaigns

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/list_meta_campaigns/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "ad_account_id": "string",
    "effective_status": "string",
    "limit": 100,
    "objective": "string",
    "status": "string"
  }
}
'

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

Authorizations

Authorization

string

header

required

API key from https://adspirer.ai/keys. Prefix sk_live_. Treat as a secret — never commit.

Headers

Idempotency-Key

string<uuid>

Client-generated UUID to make writes idempotent. Strongly recommended for write tools. A repeat call with the same key returns the cached result instead of re-executing. Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

All tool arguments are wrapped in an arguments object. The fields accepted inside arguments are listed below — required fields are marked with a red asterisk.

arguments

object

required

Input schema for listing Meta campaigns

Show child attributes

Response

Tool executed successfully. data.text carries the human-readable result (markdown-friendly). data.quota shows your current usage against the plan limit. data.structured appears when the tool emits machine-parseable structured content. data.content appears for tools that return non-text blocks (images, resources).

Returned on HTTP 200. data.text is the primary human-readable output. data.quota is always present for billable calls. data.structured is set only when the tool emits machine-parseable structured content. data.content is set only when the tool emits non-text content blocks.

data

object

required

Show child attributes

success

boolean

required

tool

string

required

Echoed tool_name from the request URL.

Last modified on April 23, 2026

List Meta Custom AudiencesUser wants to browse, list, or select Custom Audiences for targeting — DB lists, lookalike audiences, remarketing segments, website visitors, engagement audiences. Returns all Custom Audiences for the ad account with ID, name, type (subtype), approximate size, and delivery status. Workflow: 1. Call this tool to discover available custom audiences 2. Use audience IDs with campaign creation tools via `custom_audiences` parameter 3. Optionally use `excluded_custom_audiences` to exclude specific audiences When to use: - Before creating campaigns that need custom audience targeting - When user asks "which audiences do I have?" or "show me my lookalike audiences" - When setting up remarketing or DB-list campaigns

List Meta Campaigns

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/list_meta_campaigns/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "ad_account_id": "string",
    "effective_status": "string",
    "limit": 100,
    "objective": "string",
    "status": "string"
  }
}
'

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