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/5/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: This can only include users that the ads account has access to promote. Use the GET accounts/:account_id/promotable_users endpoint to retrieve a list of such users.

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/5/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
    }
  }
}