get_campaigns_by_adaccount

Retrieves campaigns from a specific Facebook ad account.

This function allows querying all campaigns belonging to a specific ad account with various filtering options, pagination, and field selection.

Args: act_id (str): The ID of the ad account to retrieve campaigns from, prefixed with 'act_', e.g., 'act_1234567890'. fields (Optional[List[str]]): A list of specific fields to retrieve for each campaign. If None, a default set of fields will be returned. See get_campaign_by_id for a comprehensive list of available fields. filtering (Optional[List[dict]]): A list of filter objects to apply to the data. Each object should have 'field', 'operator', and 'value' keys. Operators include: 'EQUAL', 'NOT_EQUAL', 'GREATER_THAN', 'GREATER_THAN_OR_EQUAL', 'LESS_THAN', 'LESS_THAN_OR_EQUAL', 'IN_RANGE', 'NOT_IN_RANGE', 'CONTAIN', 'NOT_CONTAIN', 'IN', 'NOT_IN', 'EMPTY', 'NOT_EMPTY'. Example: [{'field': 'daily_budget', 'operator': 'GREATER_THAN', 'value': 1000}] limit (Optional[int]): Maximum number of campaigns to return per page. Default is 25, max is 100. after (Optional[str]): Pagination cursor for the next page. From response['paging']['cursors']['after']. before (Optional[str]): Pagination cursor for the previous page. From response['paging']['cursors']['before']. date_preset (Optional[str]): A predefined relative date range for selecting campaigns. Options include: 'today', 'yesterday', 'this_month', 'last_month', 'this_quarter', 'maximum', 'last_3d', 'last_7d', 'last_14d', 'last_28d', 'last_30d', 'last_90d', 'last_week_mon_sun', 'last_week_sun_sat', 'last_quarter', 'last_year', 'this_week_mon_today', 'this_week_sun_today', 'this_year'. time_range (Optional[Dict[str, str]]): A custom time range with 'since' and 'until' dates in 'YYYY-MM-DD' format. Example: {'since': '2023-01-01', 'until': '2023-01-31'} updated_since (Optional[int]): Return campaigns that have been updated since this Unix timestamp. effective_status (Optional[List[str]]): Filter campaigns by their effective status. Options include: 'ACTIVE', 'PAUSED', 'DELETED', 'PENDING_REVIEW', 'DISAPPROVED', 'PREAPPROVED', 'PENDING_BILLING_INFO', 'ARCHIVED', 'WITH_ISSUES'. is_completed (Optional[bool]): If True, returns only completed campaigns. If False, returns only active campaigns. If None, returns both. special_ad_categories (Optional[List[str]]): Filter campaigns by special ad categories. Options include: 'EMPLOYMENT', 'HOUSING', 'CREDIT', 'ISSUES_ELECTIONS_POLITICS', 'NONE'. objective (Optional[List[str]]): Filter campaigns by advertising objective. Options include: 'APP_INSTALLS', 'BRAND_AWARENESS', 'CONVERSIONS', 'EVENT_RESPONSES', 'LEAD_GENERATION', 'LINK_CLICKS', 'LOCAL_AWARENESS', 'MESSAGES', 'OFFER_CLAIMS', 'PAGE_LIKES', 'POST_ENGAGEMENT', 'PRODUCT_CATALOG_SALES', 'REACH', 'STORE_VISITS', 'VIDEO_VIEWS'. buyer_guarantee_agreement_status (Optional[List[str]]): Filter campaigns by buyer guarantee agreement status. Options include: 'APPROVED', 'NOT_APPROVED'. date_format (Optional[str]): Format for date responses. Options: - 'U': Unix timestamp (seconds since epoch) - 'Y-m-d H:i:s': MySQL datetime format - None: ISO 8601 format (default) include_drafts (Optional[bool]): If True, includes draft campaigns in the results.

Returns: Dict: A dictionary containing the requested campaigns. The main results are in the 'data' list, and pagination info is in the 'paging' object.

Example: ```python # Get active campaigns from an ad account campaigns = get_campaigns_by_adaccount( act_id="act_123456789", fields=["name", "objective", "effective_status", "created_time"], effective_status=["ACTIVE"], limit=50 )

# Get campaigns with specific objectives
lead_gen_campaigns = get_campaigns_by_adaccount(
    act_id="act_123456789",
    fields=["name", "objective", "spend_cap", "daily_budget"],
    objective=["LEAD_GENERATION", "CONVERSIONS"],
    date_format="U"
)

# Get campaigns created in a specific date range
date_filtered_campaigns = get_campaigns_by_adaccount(
    act_id="act_123456789",
    fields=["name", "created_time", "objective"],
    time_range={"since": "2023-01-01", "until": "2023-01-31"}
)

# Fetch the next page if available using the pagination cursor
next_page_cursor = campaigns.get("paging", {}).get("cursors", {}).get("after")
if next_page_cursor:
    next_page = get_campaigns_by_adaccount(
        act_id="act_123456789",
        fields=["name", "objective", "effective_status", "created_time"],
        effective_status=["ACTIVE"],
        limit=50,
        after=next_page_cursor
    )
```