Recommended procedures and tips to use our API.
The Marketing API has it is own rate limiting logic. Learn about rate limits and how to deal with them. See Throttling Errors.
List of common error codes returned by the API.
How to test our API. Learn about Sandbox mode and Graph API Explorer.
How to use asynchronous requests to create ads.
Batch your API calls for greater efficiency.
Campaign, ad set, and ad objects limit the number of each object allowed in an ad account. Manage objects around those limits.
Optimize your calls to only fetch data when it changed.
Validation that occurs amongst the ad objects and parameters.
Understand the API policies; Facebook has the right to audit your activity anytime.
If you make any changes to the following scenarios, your ad will be triggered for review:
Note: Changes to bid amount, budget, and ad set schedule will not have any effect on the review status.
Additionally, if an ad enters Ad Review with the run status of "Paused", then it will remain Paused upon exiting Ad Review. Otherwise, the ad will be considered Active and ready to deliver.
For paging response data, see the Graph API Pagination.
You should store user IDs, session keys, and the ads account ID so it is easy to programmatically access them and keep them together. This is important because any calls made with an account ID belonging to one user and the session key for another user will fail with a permissions error.
Run frequent reports on your campaigns, as suggested bids change dynamically in response to bidding by competitors using similar targeting. Bid suggestions get updated within a few hours, depending upon the bidding of competitors.
Make multiple requests to the API with a single call, see:
You can also query for multiple objects by ID as follows:
To query for a specific field:
Quickly check if the response to a request has changed since you last made it, see:
Ad objects have two types of delete states: archived and deleted. You can query both archived and delted objects with the object id. However, we do not return deleted objects if you request it from another object's edge.
You can have up to 5000 archived objects at any time. You should move ad objects from archived states to deleted states if you no longer need to retrieve them via edges. To learn how states work and for sample calls see Storing Ad Objects.
People make mistakes and try to create ads that are not accepted, Error Codes provide reasons an API call failed. You should share some form of the error to users so they can fix their ads.
The Marketing API has it is own rate limiting logic and is excluded from all the graph api rate limitations. So if you make a Marketing API call, it won't be calculated into the Graph API throttling.
The Rate Limit dashboard in the app dashboard shows the current percentage of the limit used and time to reset usage. We recommend that you check the current percentage of the limit used and time to reset usage in the app dashboard. If the usage is close to the limit, reduce the number of Marketing API calls.
For more information about rate limiting in Graph API, see Rate Limiting on the Graph API.
For the Insights API rate limits, see Ads Insights Level Rate Limiting
spend_cap_actionfields are limited.
ads_management- As of v4.0, for each ad account in a one-hour time period: (100000 if your app is in the Standard tier or 300 if your app is in the Dev tier) + 40 * Num of Active ads.
custom_audience- As of v4.0, for each ad account in a one-hour time period: No more than 700000. No less than 190000 if your app is in the Standard tier or 5000 if your app is in the Dev tier + 40 * Number of Active custom audiences.
Sandbox mode is a testing environment to read and write Marketing API calls without delivering actual ads. See Sandbox Mode for Developers
Try API calls with Graph API Explorer. You can try any API call you would like to make to the Marketing API, see blog post. Select your app in
App, and grant your app
ads_read permission in
extended permissions when you create an access token. Use
ads_read if you only need Ads Insights API access for reporting. Use
ads_management to read and update ads in an account.
You can use sandbox mode to demonstrate your app for app review. However in sandbox mode you cannot create ads or ad creative. Therefore you should use hard coded ad IDs and ad creative IDs to demonstrate your use of our API for app review.
Understand the API policies; Facebook has the right to audit your activity anytime:
Be ready to adapt quickly to changes. Most changes are versioned and change windows are 90 days, ongoing.
In Statement of Rights and Responsibilities, you are financially and operationally responsible for your application, its contents, and your use of Facebook Platform and the Ads API. You should manage your app's stability and potential bugs.