--- title: "List facebook ads" method: GET path: "/3.0/facebook-ads" tags: ["facebook-ads"] --- # List facebook ads `GET /3.0/facebook-ads` ## Request - Base URL: `https://api.mailchimp.com` - URL: `https://api.mailchimp.com/3.0/facebook-ads` - Auth: one of: - HTTP bearer - OAuth 2 - Authorization code: `https://login.mailchimp.com/oauth2/authorize` - Token URL: `https://login.mailchimp.com/oauth2/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Get list of Facebook ads. ## Query parameters - `fields` string[] - `exclude_fields` string[] - `count` integer - `offset` integer - `sort_field` 'created_at' | 'updated_at' | 'end_time' - `sort_dir` 'ASC' | 'DESC' ## Response `200` List of Facebook Ad Instances - object: Contains an array of facebook ads. - `_links` object[]: A list of link types and descriptions for the API schema documents. - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'. - `rel` string: As with an HTML 'rel' attribute, this describes the type of link. - `schema` string: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to. - `targetSchema` string: For GETs, this is a URL representing the schema that the response should conform to. - `facebook_ads` object[] - `canceled_at` string, date-time: The date and time the outreach was canceled in ISO 8601 format. - `create_time` string, date-time: The date and time the outreach was created in ISO 8601 format. - `has_segment` boolean: If this outreach targets a segment of your audience. - `id` string: Unique ID of an Outreach. - `name` string: Title or name of an Outreach. - `published_time` string, date-time: The date and time the outreach was (or will be) published in ISO 8601 format. - `recipients` object: High level audience information for who the outreach targets. - `list_id` string: The unique list id. - `list_is_active` boolean: The status of the list used, namely if it's deleted or disabled. - `list_name` string: The name of the list. - `recipient_count` integer: Count of the recipients on the associated list. Formatted as an integer. - `segment_opts` object: An object representing all segmentation options. This object should contain a `saved_segment_id` to use an existing segment, or you can create a new segment by including both `match` and `conditions` options. - `conditions` union[]: Segment match conditions. There are multiple possible types, see the [condition types documentation](https://mailchimp.com/developer/marketing/docs/alternative-schemas/#segment-condition-schemas). - union - object: Segment by interaction with a specific campaign. - … - object: Segment by interaction with an Automation workflow. - … - object: Segment by poll activity. - … - object: Segment by interaction with a campaign via Conversations. - … - object: Segment by a specific date field. - … - object: Segment by use of a particular email client. - … - object: Segment by language. - … - object: Segment by member rating. - … - object: Segment by signup source. - … - object: Segment by interaction with a SurveyMonkey survey. - … - object: Segment by VIP status. - … - object: Segment by an interest group merge field. - … - object: Segment by purchases in specific items or categories. - … - object: Segment by average spent total, number of orders, total number of products purchased, or average number of products per order. - … - object: Segment by whether someone has purchased anything. - … - object: Segment by amount spent on a single order or across all orders. - … - object: Segment by purchases from a specific store. - … - object: Segment by Goal activity. - … - object: Segment by most recent interaction with a website. - … - object: Segment by similar subscribers. - … - object: Segment by a given static segment. - … - object: Segment by a specific country or US state. - … - object: Segment by a specific geographic region. - … - object: Segment by a specific US ZIP code. - … - object: Segment members whose location information is unknown. - … - object: Segment by a specific US ZIP code. - … - object: Segment by age ranges in Social Profiles data. - … - object: Segment by listed gender in Social Profiles data. - … - object: Segment by influence rating in Social Profiles data. - … - object: Segment by social network in Social Profiles data. - … - object: Segment by social network in Social Profiles data. - … - object: Segment by an address-type merge field. - … - object: Segment by an address-type merge field within a given distance. - … - object: Segment by a contact's birthday. - … - object: Segment by a given date merge field. - … - object: An individual segment condition - … - object: Segment by a given text or number merge field. - … - object: Segment by email address. - … - object: Segment by predicted gender. - … - object: Segment by predicted age. - … - object: Segment by when people subscribed. - … - `match` 'any' | 'all': Segment match type. - `prebuilt_segment_id` string: The prebuilt segment id, if a prebuilt segment has been designated for this campaign. - `saved_segment_id` union: The id for an existing saved segment. - integer - string - `segment_text` string: A description of the [segment](https://mailchimp.com/help/save-and-manage-segments/) used for the campaign. Formatted as a string marked up with HTML. - `report_summary` object: High level reporting stats for an outreach. - `click_rate` number - `clicks` integer - `conversion_rate` number - `ecommerce` object - `average_order_revenue` number - `currency_code` string - `total_revenue` number - `engagements` integer - `impressions` number - `open_rate` number - `opens` integer - `proxy_excluded_open_rate` number - `proxy_excluded_opens` integer - `proxy_excluded_unique_opens` integer - `reach` integer - `subscriber_clicks` integer - `subscribes` integer - `total_sent` integer - `unique_opens` integer - `unique_visits` integer - `visits` integer - `show_report` boolean: Outreach report availability. Note: This property is hotly debated in what it _should_ convey. See [MCP-1371](https://jira.mailchimp.com/browse/MCP-1371) for more context. - `start_time` string, date-time: The date and time the outreach was started in ISO 8601 format. - `status` 'save' | 'paused' | 'schedule' | 'scheduled' | 'sending' | 'sent' | 'canceled' | 'canceling' | 'active' | 'disconnected' | 'somepaused' | 'draft' | 'completed' | 'partialRejected' | 'pending' | 'rejected' | 'published' | 'unpublished': The status of this outreach. - `type` 'regular' | 'email-touchpoint' | 'plaintext' | 'rss' | 'reconfirm' | 'variate' | 'absplit' | 'automation' | 'facebook' | 'google' | 'autoresponder' | 'transactional' | 'page' | 'website' | 'social_post' | 'survey' | 'customer_journey' | 'sms': The type of outreach this object is. - `updated_at` string, date-time: The date and time the outreach was last updated in ISO 8601 format. - `web_id` integer: The ID used in the Mailchimp web application. For example, for a `regular` outreach, you can view this campaign in your Mailchimp account at `https://{dc}.admin.mailchimp.com/campaigns/show/?id={web_id}`. - `email_source_name` string - `end_time` string, date-time: The date and time the ad was ended in ISO 8601 format. - `needs_attention` boolean: If the ad has a problem and needs attention. - `paused_at` string, date-time: The date and time the ad was paused in ISO 8601 format. - `thumbnail` string: The URL of the thumbnail for this outreach. - `was_canceled_by_facebook` boolean - `audience` object: Audience settings - `email_source` object - `is_segment` boolean: Is the source reference a segment - `list_name` string: Associated list name to the source - `name` string: Email source name - `segment_type` string: Segment type if this source is tied to a segment - `type` string: Type of the email source - `include_source_in_target` boolean: To include list contacts as part of audience - `lookalike_country_code` string: To find similar audience in given country - `source_type` 'facebook' | 'list': List or Facebook based audience - `targeting_specs` object - `gender` 0 | 1 | 2 - `interests` object[] - `name` string - `locations` object - `cities` string[] - `countries` string[] - `regions` string[] - `zips` string[] - `max_age` integer - `min_age` integer - `type` 'Custom Audience' | 'Lookalike Audience' | 'Interest-based Audience': Type of the audience - `budget` object - `currency_code` string: Currency code - `duration` integer: Duration of the ad in seconds - `total_amount` number: Total budget of the ad - `channel` object: Channel settings - `fb_placement_audience` boolean: Is this for facebook audience - `fb_placement_feed` boolean: Is this for facebook feed - `ig_placement_feed` boolean: Is this for instagram feed - `content` object - `attachments` object[] - `call_to_action` string - `description` string - `image_url` string - `link_url` string - `name` string - `call_to_action` string - `description` string - `image_url` string - `link_url` string - `message` string - `title` string - `feedback` object: Check if this ad is connected to a facebook page - `audience` string: Feedback regarding the audience of this Ad. - `budget` string: Feedback regarding the budget of this Ad. - `compliance` string: Feedback regarding the compliance of this Ad. - `content` string: Feedback regarding the content of this Ad. - `has_audience` boolean: Check if this ad has audience setup - `has_content` boolean: Check if this ad has content - `is_connected` boolean: Check if this ad is connected to a facebook page - `site` object: Connected Site - `id` integer: The ID of this connected site. - `name` string: The name of the connected site - `url` string: The URL for this connected site. - `_links` object[]: A list of link types and descriptions for the API schema documents. - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'. - `rel` string: As with an HTML 'rel' attribute, this describes the type of link. - `schema` string: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to. - `targetSchema` string: For GETs, this is a URL representing the schema that the response should conform to. - `total_items` integer: The total number of items matching the query regardless of pagination. ## Other responses - `default`: An error generated by the Mailchimp API. --- [API](https://skmtc.dev/mailchimp/apis/mailchimp-api.md) - [All operations](https://skmtc.dev/mailchimp/apis/mailchimp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mailchimp/apis/mailchimp-api/revisions/53bf4b156855?raw)