Campaign Management

Reach Estimate¶

GET accounts/:account_id/reach_estimate¶

Determine the approximate reach of your campaigns.

The following are estimates that are functions of bid and budget:

count (daily reach)
impressions (daily impressions)
engagements (daily engagements)
estimated_daily_spend_local_micro (daily spend)

The infinite_bid_count is the maximum number of users you could reach if you won every single bid with the current targeting criteria, without respect to bid or budget.

Note: The current reach estimate implementation does not support broad targeting. It is required that you specify at least one primary targeting criterion; you can see a list of all primary targeting criteria in our campaigns targeting page.

Note: Negated keywords are not accepted.

Note: The maximum number of accepted targeting criteria is 800.

Resource URL¶

https://ads-api.twitter.com/3/accounts/:account_id/reach_estimate

Parameters¶

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
bid_amount_local_micro required	The bid amount, in micros. Type: long Example: `1500000`
campaign_daily_budget_amount_local_micro required	The daily budget, in micros. Type: long Example: `1500000`
currency required	The currency, expressed in ISO-4217. Type: string Example: `USD`
objective required	Specify the objective to retrieve the reach estimate for. Type: enum Possible values: `APP_ENGAGEMENTS`, `APP_INSTALLS`, `AWARENESS`, `FOLLOWERS`, `TWEET_ENGAGEMENTS`, `VIDEO_VIEWS`, `VIDEO_VIEWS_PREROLL`, `VIDEO_VIEWS_MIDROLL`, `WEBSITE_CLICKS`
product_type required	Specify the product type to retrieve the reach estimate for. Type: enum Possible values: `MEDIA`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEETS`, `LIVE_TV_EVENT`
age_buckets optional	Scopes the reach estimate audience by the specified age buckets. Specify a comma-separated list of targeting values. Type: enum Possible values: `AGE_13_TO_24`, `AGE_13_TO_34`, `AGE_13_TO_49`, `AGE_13_TO_54`, `AGE_OVER_13` , `AGE_18_TO_34`, `AGE_18_TO_49`, `AGE_18_TO_54`, `AGE_OVER_18` , `AGE_21_TO_34`, `AGE_21_TO_49`, `AGE_21_TO_54`, `AGE_OVER_21` , `AGE_25_TO_49`, `AGE_25_TO_54`, `AGE_OVER_25`, `AGE_35_TO_49`, `AGE_35_TO_54`, `AGE_OVER_35` , `AGE_OVER_50`
app_store_categories optional	Scopes the reach estimate audience by the specified app store categories. Specify a comma-separated list of targeting values. Type: string Example: `music`
app_store_categories_expanded optional	Scopes the reach estimate audience by expanded look-a-likes for the specified app store categories. Specify a comma-separated list of targeting values. Type: string Example: `music`
behaviors optional	Scopes the reach estimate audience by the specified behaviors. Specify a comma-separated list of targeting values. Type: string Example: `auto service buyer`
behaviors_expanded optional	Scopes the reach estimate audience by expanded look-a-likes for the specified behaviors. Specify a comma-separated list of targeting values. Type: string Example: `auto service buyer`
bid_type optional	The bidding mechanism. Type: enum Possible values: `AUTO`, `MAX`, `TARGET`
broad_keywords optional	Scopes the reach estimate audience by the specified broad keywords. Specify a comma-separated list of broad keywords. Note: Up to 300 keywords may be provided. Type: string Example: `cars`
devices optional	Scopes the reach estimate audience by the specified devices. Specify a comma-separated list of targeting values. Type: string Example: `1t`
exact_keywords optional	Scopes the reach estimate audience by the specified exact keywords. Specify a comma-separated list of exact keywords. Note: Up to 300 keywords may be provided. Type: string Example: `freebandnames`
followers_of_users optional	Scopes the reach estimate audience by the specified users’ followers. Specify a comma-separated list of user IDs. Note: Up to 100 user IDs may be provided. Type: string Example: `756201191646691328`
gender optional	Scopes the reach estimate audience by the specified gender. Use `0` for unknown, `1` for males, and `2` for females. Omit for all. Type: int Possible values: `0`, `1`, `2`
interests optional	Scopes the reach estimate audience by the specified interests. Specify a comma-separated list of targeting values. Note: Up to 100 interests may be provided. Type: int Example: `19004`
languages optional	Scopes the reach estimate audience by the specified languages. Specify a comma-separated list of targeting values. Type: string Example: `en`
locations optional	Scopes the reach estimate audience by the specified locations. Specify a comma-separated list of targeting values. Type: string Example: `b6b8d75a320f81d9`
network_operators optional	Scopes the reach estimate audience by the specified network operators. Specify a comma-separated list of targeting values. Type: string Example: `2t`
phrase_keywords optional	Scopes the reach estimate audience by the specified phrase keywords. Specify a comma-separated list of phrase keywords. Note: Up to 300 keywords may be provided. Type: string Example: `green cars`
platforms optional	Scopes the reach estimate audience by the specified platforms. Specify a comma-separated list of targeting values. Type: int Example: `4`
platform_versions optional	Scopes the reach estimate audience by the specified platform versions. Specify a comma-separated list of targeting values. Type: string Example: `s`
similar_to_followers_of_users optional	Scopes the reach estimate audience by users similar to the specified users’ followers. Specifify a comma-separated list of user IDs. Note: Up to 100 user IDs may be provided. Type: string Example: `756201191646691328`
tailored_audience optional	Scopes the reach estimate audience by the specified tailored audiences. Specify a comma-separated list of tailored audience IDs. Type: string Example: `123gpj`
tailored_audience_expanded optional	Scopes the reach estimate audience by expanded look-a-likes for the specified tailored audiences. Specify a comma-separated list of tailored audience IDs. Type: string Example: `123gpj`
wifi_only optional	Scopes the reach estimate audience by users on mobile devices using Wi-Fi connections. Type: boolean Possible values: `true`, `false`

Example Request¶

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/reach_estimate?product_type=PROMOTED_TWEETS&bid_amount_local_micro=150000&currency=USD&campaign_daily_budget_amount_local_micro=550000&objective=TWEET_ENGAGEMENTS&similar_to_followers_of_users=14230524,90420314

Example Response¶

{
  "data": {
    "impressions": {
      "min": 264,
      "max": 397
    },
    "count": {
      "min": 215,
      "max": 322
    },
    "infinite_bid_count": {
      "min": 1638,
      "max": 2457
    },
    "engagements": {
      "min": 7,
      "max": 11
    },
    "estimated_daily_spend_local_micro": {
      "min": 440000,
      "max": 660000
    }
  },
  "request": {
    "params": {
      "bid_amount_local_micro": 150000,
      "similar_to_followers_of_users": [
        14230524,
        90420314
      ],
      "product_type": "PROMOTED_TWEETS",
      "objective": "TWEET_ENGAGEMENTS",
      "account_id": "18ce54d4x5t",
      "currency": "USD",
      "campaign_daily_budget_amount_local_micro": 550000
    }
  }
}