Ad Campaign Budget Schedules

Updated: Nov 17, 2023

Copy for LLM

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

Select language

GET /v25.0/{ad-set-id}/budget_schedules HTTP/1.1
Host: graph.facebook.com

Try it in Graph API Explorer

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}/{AD_SET_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}/{AD_SET_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

Parameter	Description
`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.

Error Codes

Error Code	Description
200	Permissions error

Creating

/{ad_set_id}/budget_schedules

You can make a POST request to budget_schedules edge from the following paths:

/{ad_set_id}/budget_schedules

When posting to this edge, no Graph object will be created.

Parameters

Parameter	Description
`budget_value` int64	Actual budget increase, unit defined by BudgetValueType (e.g. 140 could be $140 or 140%) required
`budget_value_type` enum{ABSOLUTE, MULTIPLIER}	Type of budget value (e.g. absolute or multiplier) required
`time_end` int64	When the increased budget should end required
`time_start` int64	When the increased budget 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,
}

Error Codes

Error Code	Description
100	Invalid parameter

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.