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/4/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: |
bid_amount_local_micro
required
|
The bid amount, in micros. Type: long Example: |
campaign_daily_budget_amount_local_micro
required
|
The daily budget, in micros. Type: long Example: |
currency
required
|
The currency, expressed in ISO-4217. Type: string Example: |
objective
required
|
Specify the objective to retrieve the reach estimate for. Type: enum Possible values: |
product_type
required
|
Specify the product type to retrieve the reach estimate for. Type: enum Possible values: |
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: |
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: |
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: |
behaviors
optional
|
Scopes the reach estimate audience by the specified behaviors. Specify a comma-separated list of targeting values. Type: string Example: |
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: |
bid_type
optional
|
The bidding mechanism. Type: enum Possible values: |
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: |
devices
optional
|
Scopes the reach estimate audience by the specified devices. Specify a comma-separated list of targeting values. Type: string Example: |
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: |
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: |
gender
optional
|
Scopes the reach estimate audience by the specified gender. Use Type: int Possible values: |
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: |
languages
optional
|
Scopes the reach estimate audience by the specified languages. Specify a comma-separated list of targeting values. Type: string Example: |
locations
optional
|
Scopes the reach estimate audience by the specified locations. Specify a comma-separated list of targeting values. Type: string Example: |
network_operators
optional
|
Scopes the reach estimate audience by the specified network operators. Specify a comma-separated list of targeting values. Type: string Example: |
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: |
platforms
optional
|
Scopes the reach estimate audience by the specified platforms. Specify a comma-separated list of targeting values. Type: int Example: |
platform_versions
optional
|
Scopes the reach estimate audience by the specified platform versions. Specify a comma-separated list of targeting values. Type: string Example: |
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: |
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: |
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: |
wifi_only
optional
|
Scopes the reach estimate audience by users on mobile devices using Wi-Fi connections. Type: boolean Possible values: |
Example Request¶
GET https://ads-api.twitter.com/4/accounts/18ce54d4x5t/reach_estimate?product_type=PROMOTED_TWEETS&bid_amount_local_micro=150000¤cy=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
}
}
}