Ad Volume

View the volume of ads running or in review for your ad accounts. These ads will count against the ads limit per page that we will enact in early 2021. Query the number of ads running or in review for a given ad account.

View Ad Volume for Your Ad Account

To see the ad volume for your ad account:

curl -G -d "access_token=<access_token>" "https://graph.facebook.com/<VERSION>/<ad_account_ID>/ads_volume"

Response

{"data":[{"ads_running_or_in_review_count":2}]}

For information on managing ad volume, see About Managing Ad Volume.

View Running or In Review Status

To see if an ad is running or in review, we check effective_status, then configured_status, and the ad account's status:

  • If an ad has effective_status of 1 - active, we consider it in running or in review state.
  • If an ad has configured_status of active and effective_status of 9 - pending review or 17 - pending processing, we consider it a running or in review.
  • The ad can be running or in review only if the ad account status is in 1 - active, 8 - pending settlement, or 9 - in grace period.

We also determine if an ad is running or in review based on the ad set's schedule:

  • If start time is before current time, and current time is before end time, then we consider the ad running or in review.
  • If start time is before current time and the ad set has no end time, we also consider it running or in review.

For example, if the ad set is scheduled to run in the future, the ads are not running or in review. However, if the ad set is scheduled to run from now until 3 months from now, we consider the ads running or in review.

If you are using special ads scheduling features, such as day-parting, we consider the ad running or in review the whole day not just for the part of the day when the ad starts running.

Breakdown by Actors

Use the show_breakdown_by_actor field to get a breakdown of ad limits by a specific actor_id:

curl -G \
  -d "show_breakdown_by_actor=true" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads_volume"

Response

{
  "data": [
    {
      "ads_running_or_in_review_count": 0,
      "current_account_ads_running_or_in_review_count": 0,
      "actor_id": "<ACTOR_ID_1>"
    },
    {
      "ads_running_or_in_review_count": 2,
      "current_account_ads_running_or_in_review_count": 2,
      "actor_id": "<ACTOR_ID_2>"
    }
  ],
  "__fb_trace_id__": "<FB_TRACE_ID>",
  "__www_request_id__": "<WWW_REQUEST_ID>"
}

Use page_id to get the ad limits for a specific page:

curl -G \
  -d "page_id=<PAGE_ID>" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads_volume"

Response

{
  "data": [
    {
      "ads_running_or_in_review_count": 2,
      "current_account_ads_running_or_in_review_count": 2,
      "actor_id": "<ACTOR_ID>"
    }
  ],
  "__fb_trace_id__": "<FB_TRACE_ID>",
  "__www_request_id__": "<WWW_REQUEST_ID>"
}

Supported Fields

FieldDescription

actor_id

Actor that the limit is enforced against. Currently, this is always the page ID.

ads_running_or_in_review_count

Number of ads running or in review for a specific actor.

current_account_ads_running_or_in_review_count

Number of ads running or in review within the current ad account on a specific actor.

actor_name

Actor that the ads volume aggregated on. Currently, it can only be page name.

ad_limit_scope_business

Used in cases where an ad account belongs to a Business Manager and the ad account is subject to Business Manager level ad limits.


This field has the business that defines the ad limits for an ad account.

ad_limit_scope_business_manager_id

Used in cases where an ad account belongs to a Business Manager and the ad account is subject to Business Manager level ad limits.


This field has the Business Manager ID for a business that defines the ad limits for an ad account.

ad_limit_set_by_page_admin

Ad limit set by a page admin for the business that owns the ad account.

ads_running_or_in_review_count_subject_to_limit_set_by_page

Number of ads running or in review for a group of ad accounts. In this case, the group can contain ad accounts that belong to a business or individual ad accounts.


If ad limit is not set by the page owner, it returns null.


If ad limit is set by the page owner, it returns the number of ads running or in review for the group of ad accounts.

future_limit_activation_date

Starting date of ad limit that will be effective in the future.

future_limit_on_ads_running_or_in_review

Ad limit that will be effective in the future. This limit is related to the number of ads running or in review for the given actor.

limit_on_ads_running_or_in_review

Current ad limit for a given actor ID. This limit is related to the number of ads running or in review.

recommendations

Recommendations to help reduce the ad volume. Currently, supported values are:

  • zero_impression
  • learning_limited
  • top_campaigns_with_ads_under_cap
  • top_adsets_with_ads_under_cap

More information can be found in the Business Help Center.

Parameters

FieldDescription

recommendation_type

Type of the recommendation to help reduce the ad volume. Currently, supported values are:

  • zero_impression
  • learning_limited
  • top_campaigns_with_ads_under_cap
  • top_adsets_with_ads_under_cap

See more information about managing ad volume.

Sample Request

curl -G \
  -d "page_id=<PAGE_ID>" \
  -d "fields=[\"actor_id\",\"current_account_ads_running_or_in_review_count\",\"limit_on_ads_running_or_in_review\",\"future_limit_on_ads_running_or_in_review\",\"ads_running_or_in_review_count\",\"future_limit_activation_date\"]" \
  -d "access_token=<>" \
  "https://graph.facebook.com/<API-VERSION>/act_<AD_ACCOUNT_ID>/ads_volume"

Response

{
   "data": [
      {
         "actor_id": "<>",
         "current_account_ads_running_or_in_review_count": 0,
         "limit_on_ads_running_or_in_review": 1000
      }
   ],
   "fb_trace_id": "<FB_TRACE_ID>",
   "www_request_id": "<WWW_REQUEST_ID>"
}