Sign in
Ad Groups

Estimate Ad Group Reach

Estimates how many people a draft targeting spec can reach, before an ad group is created. The body takes the same targeting fields as creating an ad group — regions, demographics, detailed_targeting, audiences, languages, and devices — and nothing is persisted.

post/ad_groups/estimate_reach

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

A unique key that makes this request safe to retry. See Idempotent requests.

Request body

account_idstring

Account to estimate on behalf of. Defaults to the authenticated account.

languagesstring[]

Languages to target, as ISO 639 codes such as en or es. Empty or omitted targets all languages.

platform'meta' required

The ad network the estimate runs on.

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "audiences": {
    "exclude": [
      "adaud_xxxxxxxxxxxxxx"
    ],
    "include": [
      "adaud_xxxxxxxxxxxxxx"
    ]
  },
  "demographics": {
    "gender": "all",
    "maximum_age": 64,
    "minimum_age": 21
  },
  "detailed_targeting": {
    "behaviors": [
      {
        "behavior_type": "video",
        "id": "6007101291578",
        "name": "Recent vehicle purchase (30 days)"
      }
    ],
    "demographics": [
      {
        "id": "6002714398172",
        "name": "Recently moved",
        "type": "life_events"
      }
    ],
    "interests": [
      {
        "id": "6003193685204",
        "name": "Car wash"
      }
    ]
  },
  "devices": {
    "operating_systems": [
      {
        "minimum_version": "18.0",
        "os": "ios"
      }
    ],
    "platforms": [
      "mobile"
    ]
  },
  "languages": [
    "en"
  ],
  "platform": "meta",
  "regions": {
    "exclude": {
      "cities": [
        {
          "key": "2418046",
          "name": "Austin"
        }
      ],
      "countries": [
        "US"
      ],
      "country_groups": [
        "north_america"
      ],
      "custom_locations": [
        {
          "distance_unit": "mile",
          "latitude": 30.2672,
          "longitude": -97.7431,
          "name": "4180 Burnet Rd, Austin TX 78756",
          "radius": 25
        }
      ],
      "regions": [
        "US-TX"
      ]
    },
    "include": {
      "cities": [
        {
          "key": "2418046",
          "name": "Austin"
        }
      ],
      "countries": [
        "US"
      ],
      "country_groups": [
        "north_america"
      ],
      "custom_locations": [
        {
          "distance_unit": "mile",
          "latitude": 30.2672,
          "longitude": -97.7431,
          "name": "4180 Burnet Rd, Austin TX 78756",
          "radius": 25
        }
      ],
      "regions": [
        "US-TX"
      ]
    }
  }
}

Response

reach estimated

users_lower_boundnumber nullable required

Low end of how many people the targeting can reach. Null when the platform couldn't produce an estimate.

users_upper_boundnumber nullable required

High end of how many people the targeting can reach. Null when the platform couldn't produce an estimate.

Example response

{
  "users_lower_bound": 1500000,
  "users_upper_bound": 1800000
}

Changes

Changed in 5 of the 74 revisions of this API.13

  • ac2b9b1c6a002See the full diff
    • ○

      added the new optional request property ////

      new-optional-request-property

    • ○

      added the new optional request property ////

      new-optional-request-property

  • 6a23760847c82See the full diff
    • ○

      added the new optional request property ///

      new-optional-request-property

    • ○

      added the new optional request property ///

      new-optional-request-property

  • ae20b30817de5See the full diff
    • ○

      added the new education_majors enum value to the request property ///

      request-property-enum-value-added

    • ○

      added the new education_schools enum value to the request property ///

      request-property-enum-value-added

    • ○

      added the new work_employers enum value to the request property ///

      request-property-enum-value-added

    • ○

      added the new work_positions enum value to the request property ///

      request-property-enum-value-added

    • ○

      added the non-success response with the status

      response-non-success-status-added

  • f1020c3ecda43See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 60bbb4a6ffbc1See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 74 revisions, 1 has no diff computed.