get_adsets

Instructions

Implementation Reference

• meta_ads_mcp/core/adsets.py:70-153 (handler)

  The main handler function for the 'get_adsets' MCP tool. Lists ad sets for an account (or filtered by campaign) via Meta's Graph API. Supports status filtering, pagination (up to 200), budget enrichment (cents to currency display), and status counting.

  @mcp.tool()
  def get_adsets(
      account_id: str,
      campaign_id: Optional[str] = None,
      status_filter: Optional[str] = None,
      limit: int = 50,
  ) -> dict:
      """
      List ad sets for an account or filtered by campaign.
  
      Args:
          account_id: Ad account ID (e.g., 'act_123456789').
          campaign_id: Optional campaign ID to filter ad sets for that campaign only.
          status_filter: Filter by effective_status: 'ACTIVE', 'PAUSED', 'ARCHIVED', or 'ALL'.
          limit: Maximum results per page (default 50).
      """
      api_client._ensure_initialized()
      account_id = ensure_account_id_format(account_id)
  
      params = {"limit": str(min(limit, 100))}
  
      if status_filter and status_filter.upper() != "ALL":
          status_val = status_filter.upper()
          valid_statuses = ["ACTIVE", "PAUSED", "DELETED", "ARCHIVED"]
          if status_val in valid_statuses:
              params["filtering"] = f'[{{"field":"effective_status","operator":"IN","value":["{status_val}"]}}]'
  
      # Choose endpoint: campaign-scoped or account-scoped
      if campaign_id:
          endpoint = f"/{campaign_id}/adsets"
      else:
          endpoint = f"/{account_id}/adsets"
  
      try:
          result = api_client.graph_get(
              endpoint,
              fields=ADSET_LIST_FIELDS,
              params=params,
          )
  
          adsets = result.get("data", [])
  
          # Enrich with human-readable budget
          for a in adsets:
              if a.get("daily_budget"):
                  a["daily_budget_display"] = format_budget_cents_to_currency(a["daily_budget"])
              if a.get("lifetime_budget"):
                  a["lifetime_budget_display"] = format_budget_cents_to_currency(a["lifetime_budget"])
  
          # Paginate up to 200
          all_adsets = list(adsets)
          paging = result.get("paging", {})
          while paging.get("next") and len(all_adsets) < 200:
              after_cursor = paging.get("cursors", {}).get("after")
              if not after_cursor:
                  break
              params["after"] = after_cursor
              result = api_client.graph_get(endpoint, fields=ADSET_LIST_FIELDS, params=params)
              next_adsets = result.get("data", [])
              if not next_adsets:
                  break
              for a in next_adsets:
                  if a.get("daily_budget"):
                      a["daily_budget_display"] = format_budget_cents_to_currency(a["daily_budget"])
                  if a.get("lifetime_budget"):
                      a["lifetime_budget_display"] = format_budget_cents_to_currency(a["lifetime_budget"])
              all_adsets.extend(next_adsets)
              paging = result.get("paging", {})
  
          # Count by status
          status_counts = {}
          for a in all_adsets:
              es = a.get("effective_status", "UNKNOWN")
              status_counts[es] = status_counts.get(es, 0) + 1
  
          return {
              "total": len(all_adsets),
              "status_counts": status_counts,
              "adsets": all_adsets,
              "rate_limit_usage_pct": api_client.rate_limits.max_usage_pct,
          }
  
      except MetaAPIError:
          raise

• meta_ads_mcp/core/adsets.py:70-70 (registration)

  The @mcp.tool() decorator that registers 'get_adsets' as an MCP tool.

  @mcp.tool()

• meta_ads_mcp/core/adsets.py:51-57 (schema)

  Schema fields used when fetching ad sets via the Graph API list endpoint.

  ADSET_LIST_FIELDS = [
      "id", "name", "status", "effective_status",
      "campaign_id", "daily_budget", "lifetime_budget",
      "optimization_goal", "billing_event", "bid_strategy",
      "start_time", "end_time",
      "created_time", "updated_time",
  ]

• meta_ads_mcp/core/adsets.py:145-150 (helper)

  Return value shape including total count, status breakdown, enriched ad set list, and rate limit info.

  return {
      "total": len(all_adsets),
      "status_counts": status_counts,
      "adsets": all_adsets,
      "rate_limit_usage_pct": api_client.rate_limits.max_usage_pct,
  }

• meta_ads_mcp/core/ops.py:218-218 (helper)

  Caller in delete_campaign_structure that uses get_adsets to find all ad sets under a campaign for bulk deletion.

  camp_adsets = get_adsets(account_id, campaign_id=cid)