Meta Marketing API
Graph API Version

Campaign Budget Schedules

Budget scheduling allows you to schedule budget increases for your campaign or ad set budget based on days or times when you anticipate higher sales opportunities, peak traffic periods or other promotional time periods. You can find additional information in the Meta Business Help Center and in the About budget scheduling section

Reading

Example

Graph API Explorer
GET /v18.0/{campaign-id}/budget_schedules HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{campaign-id}/budget_schedules',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{campaign-id}/budget_schedules",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{campaign-id}/budget_schedules",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{campaign-id}/budget_schedules"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Search Parameter Usage Example :

If we have three high demand periods set up with following specs

high_demand_periods:[{
      id:1,
      time_start:1,
      time_end:3,
      ...
},{
      id:2,
      time_start:3,
      time_end:5,
      ...
},{
      id:3,
      time_start:6,
      time_end:8,
      ...
}]

A request can be made with time_start prameter as shown below

curl -X GET
 -d 'access_token={ACCESS_TOKEN}'
 https://graph.facebook.com/{API_VERSION}/{CAMPAIGN_ID}/budget_schedules?time_start=5

This request will fetch all high demand periods with time_end value greater than time_start parameter, returning

data:[{
      id:3,
      time_start:6,
      time_end:8,
      ...
}]

A similar request can be made with time_stop parameter as shown below

curl -X GET
 -d 'access_token={ACCESS_TOKEN}'
 https://graph.facebook.com/{API_VERSION}/{CAMPAIGN_ID}/budget_schedules?time_stop=3

This request will fetch all high demand periods with time_start value less than time_stop parameter, returning

data:[{
      id:1,
      time_start:1,
      time_end:3,
      ...
}]

Parameters

ParameterDescription
time_start
datetime/timestamp

Search period start time. Filters out any HDPs with stop time <= time_start from the response.

time_stop
datetime/timestamp

Search period stop time. Filters out any HDPs with start time >= time_stop from the response.

Fields

Reading from this edge will return a JSON formatted result:

{
    "data": [],
    "paging": {}
}

data

A list of HighDemandPeriod nodes.

paging

For more details about pagination, see the Graph API guide.

Creating

You can make a POST request to budget_schedules edge from the following paths:
When posting to this edge, no Graph object will be created.

Parameters

ParameterDescription
budget_value
int64

Amount of budget increase during the high demand period. Can be expressed in either an absolute amount, or a multiplier value. The type is specified through the budget value type.

Required
budget_value_type
enum{ABSOLUTE, MULTIPLIER}

Type of budget value. This sets if the specified budget value is an increase by an absolute amount or by a multiplier value.

Required
time_end
int64

Time when the high demand period should end.

Required
time_start
int64

Time when the high demand period should start.

Required

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.