Back to News for Developers

Ad scheduling

August 13, 2014ByOmid Saadati

In this blog post, we'll explain the API for ad scheduling that enables you to specify which days of the week and times of the day your ads should be delivered. Ad scheduling is set at the ad set (AdCampaign API object) and can be specified for only ad sets that have lifetime budgets (vs. daily budgets). Therefore, the schedule applies to all ad groups that are within an ad set.

The time of the day for a schedule should be exact hour boundaries (e.g., 10 am - 2 pm) and should be at least 1 hour apart.

Here is an example for creating a campaign with a schedule that runs every day 9 am - 12 pm.

curl \ 
-F "pacing_type=['day_parting']" \ 
-F 'campaign_schedule=[{"start_minute":540,"end_minute":720,"days":[1,2,3,4,5]}]' \ 
-F "name='My campaign with ad scheduling'" \ 
-F “campaign_group_id=12345” \
-F "lifetime_budget=2500" \ 
-F "end_time=1392240667" \
-F "access_token=___" \{ad_account_id}/adcampaigns

The following two additional parameters in the above call are related to ad scheduling.

pacing_type: set this parameter to an array with one value day_parting.

campaign_schedule:specifies the delivery schedule for the ad set. Each entity in the array has three parameters.

  • start_time: start time in the number of minutes passed from 12 am.
  • end_time: end time in the number of minutes passed from 12 am
  • days: an array of integers between 0-6, where 0 represents Sundays and 6 represents Saturdays.

You can change or turn off a campaign's schedule through the API. But, please note that changing a campaign's schedule frequently might affect pacing of the campaign and its delivery negatively (see pacing for more information).

As you might have noticed in the above example, the campaign_schedule parameter doesn’t specify a time zone value. This is because our ad system applies the schedule based on time zone of the audience that the ad targets. For example, let’s say that for the above campaign, you have an ad group that targets people who live in San Francisco and Colorado state. Then, the ad will be delivered to people in San Francisco 9 am - 12 pm PDT and to people in Colorado 9 am - 12 pm MDT.

Because our ads reporting still reports all metrics in an ad account’s time zone, if your scheduled campaign targets people in a time zone that is different from that of your ad account, you will see delivery outside the scheduled time intervals in your ad account. For example, if the ad account time zone for the above campaign is ET, then you will see delivery (impressions, clicks, conversions) between 11 am - 3 pm ET every day. If your system incorrectly expects delivery 9 am - 12 pm ET (based on the ad set schedule), it might falsely detect an under delivery issue and make an incorrect decision.

To infer the delivery schedule in the ad account’s time zone, you need the following information.

  • The geo targeting specs (country, city, region, and zip codes) for all the ad groups in the ad set
  • A mapping between various geo targeting elements and their time zone

Once you have the following, you can transform the schedule (time/day) from local time zones for each targeting spec to the ad account time zone and infer the complete delivery schedule in the ad account’s time zone.


Q: To implement ad scheduling, could I just pause/resume an ad set based on a desired schedule rather than implement the above API?

A: Updating an ad set or ad group’s schedule for controlling delivery based on a schedule results in suboptimal performance. This is because frequent pausing/resuming of ads affects pacing negatively, which could result in under delivery. See pacing for more information.

Ad Scheduling Reference doc: