-t
to trace the call, roughly equivalent to cURL’s -v
option.
For this example, we will create a Promoted Ads campaign that will be targeted by keyword.
objective
on line items.
The parameter used on the line item write endpoints and returned on the read endpoints, is objective
. This field has the following possible values as of today:
APP_ENGAGEMENTS
APP_INSTALLS
FOLLOWERS
ENGAGEMENTS
REACH
VIDEO_VIEWS
PREROLL_VIEWS
WEBSITE_CLICKS
APP_ENGAGEMENTS
, CPAC or CPI for APP_INSTALLS
, CPLC for WEBSITE_CLICKS
, CPF for FOLLOWERS
, CPE for ENGAGEMENTS
, and CPM for REACH
.
Mobile app promotion campaigns are required to contain either the APP_ENGAGEMENTS
or APP_INSTALLS
objective.
Note: Line items with different objectives are not allowed under the same campaign.
Campaign objective | API objective | Media in Tweets | Pricing model |
---|---|---|---|
App re-engagements | APP_ENGAGEMENTS | Image or video app download card required. | CPAC |
App installs | APP_INSTALLS | Image or video app download card required. | CPAC or CPI (set using charge_by ) |
Reach | REACH | No restrictions. | CPM |
Followers | FOLLOWERS | Tweet not required, but recommended. There are no media restrictions on Tweets for Followers campaigns, though we recommend text-only Tweets. More information | CPF |
Engagements | ENGAGEMENTS | No restrictions. | CPE |
Video Views | VIDEO_VIEWS | Video conversation card, video, or GIF required. | CPV or cost per 3s/100% view |
Pre-roll views | PREROLL_VIEWS | Video required. | CPV or cost per 3s/100% view |
Website Clicks | WEBSITE_CLICKS | Website card recommended, but not required. Tweet must have either a website card or a website link (not both). | CPLC |
funding_instruments
on an account, see GET accounts/:account_id/funding_instruments and GET accounts/:account_id/funding_instruments/:funding_instrument_id for the details of a specific one.
account_id
, funding instrument id
, funding instrument type
, description
, and io_header
(insertion order header ID). Note that a single io_header
may be associated with multiple funding instruments.
Funding ability: able_to_fund
and reasons_not_able_to_fund
.
Time: created_at
, updated_at
, start_time
, and end_time
represented by a string, formatted as “%Y-%m-%dT%l:%M:%S%z”.
Boolean status: paused
, deleted
, and cancelled
(true or false).
Financial: currency
(ISO-4217 format), credit_limit_local_micro
, credit_remaining_local_micro
, and funded_amount_local_micro
. The value of a currency is represented in micros. For USD, $5.50 is encoded as 5.50*1e6, or 5,500,000. To represent a “whole value”, you need to multiply the local micro by 1e6 (1_000_000) for all currencies.
credit_limit_local_micro
is only valid for CREDIT_CARD
or CREDIT_LINE
type funding instruments and represents the credit limit for that instrument.
funded_amount_local_micro
is only valid for INSERTION_ORDER
type funding instruments and represents the allocated budget.
credit_remaining_local_micro
is valid for CREDIT_LINE
and AGENCY_CREDIT_LINE
type funding instruments. It represents the credit_limit_local_micro
minus the amount already spent on that funding instrument. It does not represent the difference between funded_amount_local_micro
and the amount spent. We draw a distinction between credit limit and funded amount because they represent different underlying funding methods and spending agreements we have with advertisers.
CREDIT_LINE
type).
NETWORK_OPERATOR
from GET targeting_criteria/network_operators.
New Mobile Device Targeting: Reach users based on the date that they first accessed X via their device, using the targeting type NETWORK_ACTIVATION_DURATION
using operator_type of LT for less than and GTE
for greater than or equal.
Platforms, Platform Versions, Devices, and Wifi-Only: Allows targeting of mobile devices across a variety of vectors. Platforms is a high-level targeting type that can hit broad categories of phone. Example values are iOS
and Android
. Devices allow you to target users of specific mobile devices, for example the iPhone 5s
, Nexus 4
, or Samsung Galaxy Note
. Platform versions allow you to target users of versions of specific mobile operating systems, down to the point release. Examples include iOS 7.1 and Android 4.4. Wifi-Only allows you to target only those users who are using their devices on a WiFi network; if this is not set, users using the carrier connection as well as WiFi will be targeted.
TV_SHOW
targeting type. Use the GET targeting_criteria/tv_markets and GET targeting_criteria/tv_shows endpoints to determine TV shows available.
Tweet Engager Retargeting
Tweet engager retargeting enables advertisers to target audiences across devices who have previously been exposed to or engaged with their promoted or organic Tweets on X. With this targeting advertisers can follow up with people who saw or engaged with an advertiser’s content on X and are most likely to further engage or convert with subsequent messaging or offers. Users will be eligible for targeting within minutes of exposure or engagement and will remain eligible for up to 90 days afterwards for engagements and 30 days for exposures.
Tweet Engager Targeting Types:
ENGAGEMENT_TYPE
which accepts either IMPRESSION
or ENGAGEMENT
as a targeting value. This specifies whether you wish to target exposed users (IMPRESSION
) or engaged users (ENGAGEMENT
).CAMPAIGN_ENGAGEMENT
uses a campaign ID as the targeting value. Users who engaged with or were exposed to this campaign (depending on ENGAGEMENT_TYPE
) are the ones who will be targeted.USER_ENGAGEMENT
which uses the promoted user ID as the targeting value to target users who were exposed to or engaged with an advertiser’s organic content (depending on ENGAGEMENT_TYPE
). This must be the promoted user ID associated with the Ads account.ENGAGEMENT_TYPE
is required in addition to at least one valid CAMPAIGN_ENGAGEMENT
or USER_ENGAGEMENT
value. Both tweet engager targeting types may be present and multiple campaigns may be targeted on a given line item.
Video Viewer Targeting: Video viewer targeting builds on Tweet engager targeting to enable advertisers to target audiences who have previously watched part or all of a video on X. Advertisers can target organic videos, promoted videos, or both. Promoted videos are not limited to video view objective campaigns or line items.
Video Viewer Targeting Types:
VIDEO_VIEW
for users who have clicked to play the video or have viewed 3 seconds of autoplayVIDEO_VIEW_PARTIAL
for users who have viewed 50% of the videoVIDEO_VIEW_COMPLETE
for users who have viewed at least 95% of the videoENGAGEMENT_TYPE
is used:
CAMPAIGN_ENGAGEMENT
uses a campaign ID as the targeting value. Users who watched a video (based on ENGAGEMENT_TYPE
) in this campaign are the ones who will be targeted.USER_ENGAGEMENT
which uses the promoted user ID as the targeting value to target users who watched a video (based on ENGAGEMENT_TYPE
) in an advertiser’s organic content. This must be the promoted user ID associated with the Ads account.“Primary” Types | Other Types |
Followers | Locations |
Tailored Audiences | Gender |
Interests | Languages |
Keywords | Devices and platforms |
TV | Age |
standard_delivery
parameter to false
to set the pace to accelerated delivery (see GET accounts/:account_id/campaigns).
Notes
Campaign Objective | Legacy | Ads API v10+ |
App Installs | bid_type = AUTO bid_unit = APP_INSTALLS charge_by = APP_CLICKS | goal = APP_INSTALLS bid_strategy = AUTO |
Website Clicks | bid_type = TARGET (Note: bid_unit was not needed for some campaign objectives) | bid_strategy = TARGET |
bid_strategy
setting on line items may be set with a value of TARGET
to enable target bidding on relevant campaign objectives, such as:
WEBSITE_CLICKS
WEBSITE_CONVERSIONS
APP_INSTALLS
APP_ENGAGEMENTS
REACH
app_id
or consumer_secret
for the X app that will be used for Ads API access. You can view and edit your existing X apps via the app dashboard if you are logged into your X account on developer.x.com. If you need to create a X app, you will need to have an approved developer account. X allows one app for production+sandbox and one optional app for sandbox-only access. The X app must be created on a corporate, partner-controlled X handle.
app_id
, the X user_id
of the X handle which is to be onboarded and a callback URL and other fields documented below.Name | Type | Description |
callback_url | URL encoded string | user will be redirected to this url after the account link process completes, regardless of outcome. See the partner redirect url section for protocol details |
client_app_id | integer | X API client app id, used to identify the managing partner |
promotable_user_id | integer | X user_id of the @handle whose promotions are to be managed by the managing partner. Used to make sure it is the same as the user who logs into ads.x.com to complete the linking process |
fi_description | URL encoded String (max 255 characters) | funding instrument name. This will be displayed in the description field in the API when the funding instrument is retrieved. If a funding_instrument description is given, the existing funding_instrument will be paused, and a new managed partner funding instrument will be set up. (if one exists with the same name, nothing will happen) |
timezone | String, in Area/Location format | This will be the timezone used to determine the day to which daily budgets apply, and in which charges will be aggregated |
currency | ISO 4217 Currency Code | Currency that will be used to enter bids, and in which charges will be billed |
country | ISO 3166-1 alpha 2 Country Code | Billing Country for the account |
signature | URL encoded, base64 encoded binary code, as explained below | signature that combines a shared secret and the other parameters to verify authenticity of the call, as well as validity of the parameters. |
Name | Type | Description |
status | string | OK an account was created, or an existing, eligible account was found. ACCOUNT_INELIGIBLE if partner specific constraints are not met USER_MISMATCH the X account used to sign into ads.x.com was different from the promotable_user_id on the account link request INCOMPLETE_SERVING_BILLING_INFO timezone, currency or country were not specified INVALID_COUNTRY an invalid country value was given INVALID_CURRENCY an invalid currency value was given INVALID_TIMEZONE an invalid timezone value was given |
account_id | URL encoded string | X ads account id of the linked account |
funding_instrument_id | URL encoded string | ID of the active partner managed funding instrument |
signature | URL encoded, base64 encoded binary code, as explained below | Base64 encoded HMAC-SHA1 signature that combines a shared secret and the other parameters to verify authenticity of the call, as well as validity of the parameters. To make sure the callback url is only valid for the X user_id that the account link process was intended for, the X user_id is to be appended to the shared secret (using &) when signing the request. |
user_id
that the account link process was intended for, the X user_id
is to be appended to the shared secret (using &) when signing the request.
/link_managed_account
and the callback url are valid, the requests need to be signed at the source and verified by the recipient before the recipient takes action on them. Signing the request with a secret that is shared between X and the managing partner ensures that each party only accepts requests sent by the authorized counterpart.
The signature generation algorithm is similar to the one used in OAuth.
Create a signature base string as follows:
KBxQMMSpKRrtg9aw3qxK4fTXvUc=
This signature is then added (percent encoded) to the end of the original url in the signature parameter (step 4):
https://ads.x.com/link\_managed\_account?callback\_url=https%3A%2F%2Fmanagingpartner.com%2Flink\_account\_callback&client\_app\_id=12345&fi\_description=some%20name&promotable\_user\_id=1&signature=KBxQMMSpKRrtg9aw3qxK4fTXvUc%3D
Signing a partner redirect url (account link request callback) The URL to sign, assuming a GET request:
https://managingpartner.com/link\_account\_callback?status=OK&account\_id=ABC&funding\_instrument_id=DEF
This url has the following parameters:
account_id
= ABC
, funding_instrument_id
= DEF
and status
= OK
The base string consisting of http method and url without parameters, steps a - d, looks like:
GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&“
The query string, produced by the substeps of e, looks like:
account_id=ABC&funding_instrument_id=DEF&status=OK
The percent encoded query string looks like:
account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK
The complete base string, combining steps a - d and e:
GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK
Using the hmac-sha1 algorithm we will sign this with the word “secret” and the X user id for which the original link request was made, 1 (promotable_user_id
= 1 from above) as the key, “secret&1”.
The result is Base64 encoded, and presented without the final “\n” (steps 2 and 3): jDSHDkHJIFXpPLVxtA3a9d4bPjM=
This signature is then added (percent encoded) to the end of the original url in the signature parameter (step 4):
https://managingpartner.com/link\_account\_callback?&status=OK&account\_id=ABC&funding\_instrument_id=DEF&signature=jDSHDkHJIFXpPLVxtA3a9d4bPjM%3D
placements
parameter. The possible values are:
ALL_ON_TWITTER
PUBLISHER_NETWORK
TWITTER_PROFILE
TWITTER_SEARCH
TWITTER_TIMELINE
SPOTLIGHT
TREND
product_type
and objective
determine which placements are allowed. The GET line_items/placements endpoint can be used to retrieve the valid placement options for each product type.
Additionally, the following table lists the valid placement and objective combinations.
Objective | ALL_ON_TWITTER | TWITTER_PROFILE | TWITTER_SEARCH | TWITTER_TIMELINE |
---|---|---|---|---|
APP_ENGAGEMENTS | ✔ | ✔ | ✔ | ✔ |
APP_INSTALLS | ✔ | ✔ | ✔ | ✔ |
REACH | ✔ | ✔ | ✔ | ✔ |
FOLLOWERS | ✔ | ✔ | ✔ | ✔ |
ENGAGEMENTS | ✔ | ✔ | ✔ | ✔ |
VIDEO_VIEWS | ✔ | ✔ | ✔ | ✔ |
PREROLL_VIEWS | ✔ | ✔ | ✔ | ✔ |
WEBSITE_CLICKS | ✔ | ✔ | ✔ | ✔ |
TWITTER_PROFILE
placement.
Note: TWITTER_SEARCH
requires keyword targeting.
Note: The REACH
objective must include TWITTER_TIMELINE
placement. It can have either ALL_ON_TWITTER
, any combination of placements that include TWITTER_TIMELINE
, or TWITTER_TIMELINE
on its own.
media_category=amplify_video
on the initial INIT
using this endpoint. You’ll upload the video in chunks. Once the STATUS
returns a state
of succeeded
you may continue with the next steps. More on the uploading of media using the chunked endpoint can be found in our Promoted Video Overview.
STATUS
command is succeeded
, you’ll use the media_key returned from that endpoint to add the video to the advertiser’s media library, using the POST accounts/:account_id/media_library endpoint.
objective
of VIDEO_VIEWS_PREROLL
, and a product_type
of MEDIA
. The categories
parameter must also be set to the appropriate advertiser business categories.
categories
parameter to “Science & Education”, the entire set of iab_categories
i.e., "IAB5", "IAB15"
must be set for the line item, like so:
VIDEO_VIEWS_PREROLL
objective does not utilize Promoted Tweets or Cards. Instead, the video creative is associated with your ad group (line item) and the CTA information is associated with a preroll_call_to_action
entity. The POST accounts/:account_id/preroll_call_to_action endpoint allows you to control the button CTA and the destination URL.
CONTENT_PUBLISHER_USER
as negated targeting to exclude the ad from being paired with a set of users. Provide the X user_id
or publisher_user_id for the handles to exclude.
The GET publishers endpoint can be used to retrieve the list of user_id to exclude for Content Categories. The publisher_user_id returned in the GET curated_categories response can be used to retrieve a similar exclusion list for Curated Categories.
Note: A maximum of 5 publisher_user_id can be excluded for Curated Categories and 50 user_id for Content Categories.
VIDEO_VIEWS_PREROLL
campaigns are available using our stats endpoints.
targeting_type
to unordered_keywords
or phrase_keywords
for line items.
ALL_ON_TWITTER
or TWITTER_TIMELINE
POST accounts/:account_id/line_itemsBROAD_KEYWORD
and set your keyword value(s). POST accounts/:account_id/targeting_criteriahttps://ads-api.x.com/12/accounts
Parameters
Name | Description |
---|---|
account_ids optional | Scope the response to just the desired account IDs by specifying a comma-separated list of identifiers. Type: string Example: 18ce54d4x5t |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
q optional | An optional query to scope resource by name . Note: This performs case-insensitive prefix matching. Type: string Min, Max length: 1 , 255 |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true , false |
https://ads-api.x.com/12/accounts/:account_id
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 |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t
Example Response
https://ads-api-sandbox.x.com/12/accounts
Parameters
None
Example Request
POST https://ads-api-sandbox.x.com/12/accounts
Example Response
https://ads-api.x.com/12/accounts/:account_id
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 |
name optional | The name of account. Type: string Example: API McTestface |
industry_type optional | Industry that the account is associated with. Type: string Possible values: AGENCY , BUSINESS_TO_BUSINESS , ONLINE_SERVICES , EDUCATION , FINANCIAL , HEALTH , GOVERNMENT , MEDIA , MOBILE , RESTAURANT , RETAIL , TECHNOLOGY , TRAVEL , OTHER |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t?name='API McTestface 2'&industry_type=TECHNOLOGY
Example Response
https://ads-api-sandbox.x.com/12/accounts/:account_id
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 |
DELETE https://ads-api-sandbox.x.com/12/accounts/gq12fh
Example Response
https://ads-api.x.com/12/accounts/:account_id/account_apps
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 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_apps
Example Response
entity_id
specified in the request.
Note: This endpoint is currently in beta and requires allowlisting.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/account_history
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Type: string Example: 18ce54d4x5t |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
entity_type required | The entity type to retrieve data for. Type: enum Example: PROMOTED_TWEET Possible values: CAMPAIGN , LINE_ITEM , PROMOTED_TWEET , TARGETING_CRITERIA , PROMOTED_ACCOUNT |
entity_id required | The specific entitiy to retrieve data for. Type: string Example: 8u94t |
start_time required | Scopes the retrieved data to the specified start time, expressed in ISO 8601. Note: Must be expressed in whole hours (0 minutes and 0 seconds). Type: string Example: 2017-05-19T07:00:00Z |
end_time required | Scopes the retrieved data to the specified end time, expressed in ISO 8601. Note: Must be expressed in whole hours (0 minutes and 0 seconds). Type: string Example: 2017-05-26T07:00:00Z |
user_id optional | Scopes the response to a specific user. Type: long Example: 3271358660 |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_history?entity_type=CAMPAIGN&entity_id=fc3h5&count=1
Example Response
categories
for Ad Groups (line_items
) to describe an advertiser’s brand to publishers.
Note: These categories apply only to line_items
with the PREROLL_VIEWS
objective and are separate from the content_categories
used for targeting criteria.
Each advertiser_business_categories
represents a collection of IAB Categories. When creating an Ad Group with the PREROLL_VIEWS
objective, one or two advertiser_business_categories
must be set for the Ad Group. This can be done by setting the value of the categories
request parameter on the line item endpoint to the set of corresponding iab_categories
available through this endpoint.
Additional details can be found in the Video Views Preroll Objective Guide
Resource URL
https://ads-api.x.com/12/advertiser_business_categories
Parameters
No request parameters
Example Request
GET https://ads-api.x.com/12/advertiser_business_categories
Example Response
Content-Type: application/json
header.
Note: 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.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/audience_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 |
targeting_criteria required | A JSON object containing all the parameters for the targeting criteria objects. A list of required and optional targeting criteria parameters are available on the POST accounts/:account_id/targeting_criteria endpoint. |
operator_type optional | Specify the relationship that the targeting criterion should have. For example, to set negated targeting, use operator_type=NE .Type: enum Possible values: EQ , NE Default: EQ |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/audience_estimate
ACCOUNT_ADMIN
: Full access to modify campaigns and view stats, including the ability to add or remove users and change settingsAD_MANAGER
: Full access to modify campaigns and view stats, but cannot add or remove users or change settingsCREATIVE_MANAGER
: Access to modify creatives and view previews, but no access to create or modify campaignsCAMPAIGN_ANALYST
: Access to view campaigns and view stats, but no access to create or modify campaignsANALYST
(“Organic Analyst” on ads.x.com): Access to view organic analytics and audience insights, but no access to create, modify, or view campaignsPARTNER_AUDIENCE_MANAGER
: API-only access to view and modify data partner audiences, but no access to campaigns, creatives, or other audience types.TWEET_COMPOSER
permission indicates that the authenticated user can create nullcasted (or “Promoted-only”) Tweets on behalf of the advertiser. This is only available for users with ACCOUNT_ADMIN
, AD_MANAGER
, or CREATIVE_MANAGER
access.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/authenticated_user_access
Parameters
None
Example Request
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/authenticated_user_access
Example Response
https://ads-api.x.com/12/bidding_rules
Parameters
Name | Description |
---|---|
currency optional | The type of a currency to filter results by, identified using ISO-4217. This is a three-letter string “USD” or “EUR”. Omit this parameter to retrieve all bidding rules. associated with the authenticating user. Type: string Example: USD |
GET https://ads-api.x.com/12/bidding_rules?currency=USD
Example Response
https://ads-api.x.com/12/accounts/:account_id/campaigns
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 |
campaign_ids optional | Scope the response to just the desired campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8wku2 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
funding_instrument_ids optional | Scope the response to just the campaigns under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: lygyi |
q optional | An optional query to scope resource by name .Type: string Min, Max length: 1 , 255 |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_draft optional | Include draft campaigns results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2
Example Response
https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id
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 |
campaign_id required | A reference to the campaign you are operating with in the request. Type: string Example: 8wku2 |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2
Example Response
https://ads-api.x.com/12/accounts/:account_id/campaigns
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 |
funding_instrument_id required | The identifier for the funding instrument to create the campaign under. Type: string Example: lygyi |
name required | The name for the campaign. Maximum length: 255 characters. Type: string Example: demo |
budget_optimization optional | Select the type of budget optimization to be applied Type: enum Default: CAMPAIGN Possible values: CAMPAIGN , LINE_ITEM |
daily_budget_amount_local_micro sometimes required | The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. Note: This should be less than or equal to the total_budget_amount_local_micro and is required for most Funding Insturment types.Type: long Example: 5500000 |
entity_status optional | The campaign status. Type: enum Default: ACTIVE Possible values: ACTIVE , DRAFT , PAUSED |
purchase_order_number optional | The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters. Type: string Example: D00805843 |
standard_delivery optional | Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Only available when budget_optimization is set to CAMPAIGN .Type: boolean Default: true Possible values: true , false |
total_budget_amount_local_micro optional | The total budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: 37500000 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?funding_instrument_id=lygyi&name=demo&daily_budget_amount_local_micro=140000000&entity_status=PAUSED&budget_optimization=CAMPIAGN&standard_delivery=false
Example Response
Content-Type
of application/json
is required.errors
object.operation_errors
object.https://ads-api.x.com/12/batch/accounts/:account_id/campaigns
Parameters
Name | Description |
---|---|
operation_type required | The per item operation type being performed. Type: enum Possible values: Create , Delete , Update |
params required | A JSON object containing all the parameters for the campaign objects. For a list of required and optional campaign parameters, see here. |
POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/campaigns
https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id
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 |
campaign_id required | A reference to the campaign you are operating with in the request. Type: string Example: 8wku2 |
budget_optimization optional | Select the type of budget optimization to be applied Type: enum Default: CAMPAIGN Possible values: CAMPAIGN , LINE_ITEM |
daily_budget_amount_local_micro optional | The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Note: This should be less than or equal to the total_budget_amount_local_micro .Type: long Example: 5500000 |
entity_status optional | The campaign status. Type: enum Possible values: ACTIVE , PAUSED |
name optional | The name for the campaign. Maximum length: 255 characters. Type: string Example: demo |
purchase_order_number optional | The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters. Type: string Example: D00805843 |
standard_delivery optional | Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Only available when budget_optimization is set to CAMPAIGN .Type: boolean Default: true Possible values: true , false |
total_budget_amount_local_micro optional | The total budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: 140000000 |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000
Example Response
https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id
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 |
campaign_id required | A reference to the campaign you are operating with in the request. Type: string Exampple: 8yn7m |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m
Example Response
categories
to be set as targeting_criteria
for a line item.
Each content_category
maps to one or more IAB Categories. This can be done by setting the targeting_type
to IAB_CATEGORY
on the batch targeting_critera
endpoint to include the set of corresponding iab_categories
returned by the content_categories
request. Failure to do so will result in a validation error.
Publisher details for each of these content categories can be retrieved using the GET publishers endpoint.
Additional details can be found in the Video Views Pre-roll Objective Guide.
Resource URL
https://ads-api.x.com/12/content_categories
Parameters
No request parameters
Example Request
GET https://ads-api.x.com/12/content_categories
Example Response
country_codes
Each curated_category
is only available in specific countries specified by the country_codes
in the response.
Additional details can be found in the Video Views Pre-roll Objective Guide.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/curated_categories
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 |
country_codes required | Scope the response to just the desired countries by specifying a comma-separated list of two letter ISO country codes. Up to 200 IDs may be provided. Type: string Example: US |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories?country_codes=US
Example Response
curated_category_id
Each curated_category
is only available in specific countries specified by the country_codes
in the response.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/curated_categories/:curated_category_id
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 |
curated_category_id required | A reference to the Curated Category you are operating with in the request. Type: string Example: 9ddrgesiap6o |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories/9ddrgesiap6o
Example Response
https://ads-api.x.com/12/accounts/:account_id/features
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 |
feature_keys optional | An optional parameter that enables querying for a specific feature key. Requests may include multiple comma-separated keys. Note: Only the features that are accessible by this account will be included in the response. Type: enum Possible values: REACH_AND_FREQUENCY_ANALYTICS , REACH_FREQUENCY_CAP , WEBSITE_CLICKS_CPM_BILLING |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/features
Example Response
https://ads-api-sandbox.x.com/12/accounts/:account_id/features
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: gq180y |
feature_keys required | A comma-separated list of account features to add to the account. Type: enum Possible values: AGE_TARGETING , ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE , AWARENESS_OBJECTIVE , BRAND_TPN , CHARGE_FOR_GOOD_CLICK , CONVERSATION_CARD , CONVERSATION_CARD_FOUR_OPTIONS , CONVERSATION_CARD_UNLOCK , CPI_CHARGING , DIRECT_MESSAGE_CARD , DR_TAP , ENGAGER_RETARGETING , EVENT_TARGETING , INSTALLED_APP_CATEGORY_TARGETING , MOBILE_CONVERSION_TRANSACTION_VALUE , OPTIMIZED_ACTION_BIDDING , REACH_AND_FREQUENCY_ANALYTICS , REACH_FREQUENCY_CAP , VALIDATED_AGE_TARGETING , VIDEO_VIEWS_MIDROLL_OBJECTIVE , PREROLL_VIEWS_OBJECTIVE , VIDEO_APP_DOWNLOAD_CARD |
POST https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=VALIDATED_AGE_TARGETING
Example Response
https://ads-api-sandbox.x.com/12/accounts/:account_id/features
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: gq180y |
feature_keys required | A comma-separated list of account features to remove from the account. Type: enum Possible values: AGE_TARGETING , ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE , AWARENESS_OBJECTIVE , BRAND_TPN , CHARGE_FOR_GOOD_CLICK , CONVERSATION_CARD , CONVERSATION_CARD_FOUR_OPTIONS , CONVERSATION_CARD_UNLOCK , CPI_CHARGING , DIRECT_MESSAGE_CARD , DR_TAP , ENGAGER_RETARGETING , EVENT_TARGETING , INSTALLED_APP_CATEGORY_TARGETING , MOBILE_CONVERSION_TRANSACTION_VALUE , OPTIMIZED_ACTION_BIDDING , REACH_AND_FREQUENCY_ANALYTICS , REACH_FREQUENCY_CAP , VALIDATED_AGE_TARGETING , VIDEO_VIEWS_MIDROLL_OBJECTIVE , PREROLL_VIEWS_OBJECTIVE , VIDEO_APP_DOWNLOAD_CARD |
DELETE https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=PREROLL_VIEWS_OBJECTIVE
Example Response
https://ads-api.x.com/12/accounts/:account_id/funding_instruments
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 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
funding_instrument_ids optional | Scope the response to just the desired funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: lygyi |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments
Example Response
https://ads-api.x.com/12/accounts/:account_id/funding_instruments/:id
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 |
funding_instrument_id required | A reference to the funding instrument you are operating with in the request. Type: string Example: lygyi |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments/lygyi
Example Response
https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments
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: gq1844 |
currency required | The currency, expressed in ISO-4217. Type: string Example: USD |
start_time required | The date for the funding instrument to become active and usable, expressed in ISO 8601. Type: string Example: 2017-05-19T07:00:00Z |
type required | The type of funding instrument to create. Type: enum Possible values: AGENCY_CREDIT_LINE , CREDIT_CARD , CREDIT_LINE , INSERTION_ORDER , PARTNER_MANAGED |
end_time sometimes required | The date for the funding instrument to become inactive, expressed in ISO 8601. Type: string Example: 2017-05-26T07:00:00Z |
credit_limit_local_micro optional | The total credit available against this funding instrument. Note: Only applicable to some funding instrument types. Type: long Example: 37500000 |
funded_amount_local_micro optional | The total budget amount allocated to this funding instrument. Note: Only applicable to some funding instrument types. Type: long Example: 37500000 |
POST https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments?currency=USD&start_time=2017-07-10T00:00:00Z&type=INSERTION_ORDER&end_time=2018-01-10T00:00:00Z&funded_amount_local_micro=140000000000
Example Response
https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments/:funding_instrument_id
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: gq1844 |
funding_instrument_id required | A reference to the funding instrument you are operating with in the request. Type: string Exampple: hxt82 |
DELETE https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments/hxt82
Example Response
categories
for ad groups (line_items
).
Resource URL
https://ads-api.x.com/12/iab_categories
Parameters
Name | Description |
---|---|
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of categories. See Pagination for more information. Type: string Example: gc-ddf4a |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/iab_categories?count=2
Example Response
https://ads-api.x.com/12/accounts/:account_id/line_items
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 |
campaign_ids optional | Scope the response to just the line items under specific campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8gdx6 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
funding_instrument_ids optional | Scope the response to just the line items under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: lygyi |
line_item_ids optional | Scope the response to just the desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8v7jo |
q optional | An optional query to scope resource by name .Type: string Min, Max length: 1 , 255 |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_draft optional | Include draft campaigns results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?line_item_ids=itttx
Example Response
https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id
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 |
line_item_id required | A reference to the line item you are operating with in the request. Type: string Example: 8v7jo |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/itttx
Example Response
product_type
and objective
.
When using the PROMOTED_ACCOUNT
product type, associating a Tweet with the line_item
will add timeline placements on mobile in addition to the standard PROMOTED_ACCOUNT
placement.
Setting either android_app_store_identifier
or ios_app_store_identifier
will automatically add the targeting criteria for the line item matching the mobile app being promoted; for example, passing in ios_app_store_identifier
would add PLATFORM
targeting criteria for iOS
.
Note: There is a limit of 100 line items per campaign and 256 active line items across all campaigns.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/line_items
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 |
campaign_id required | The identifier for the campaign to create the line item under. Type: string Example: 8slvg |
end_time required | The time, expressed in ISO 8601, that the line item will stop serving. Type: string Example: 2017-10-05T00:00:00Z |
objective required | The campaign objective for this line item. Type: enum Possible values: APP_ENGAGEMENTS , APP_INSTALLS , REACH , FOLLOWERS , ENGAGEMENTS , VIDEO_VIEWS , PREROLL_VIEWS , WEBSITE_CLICKS |
placements required | The placement location(s) for this line item to display in. Specify a comma-separated list of placement values. Type: enum Possible values: ALL_ON_TWITTER , PUBLISHER_NETWORK , TAP_BANNER , TAP_FULL , TAP_FULL_LANDSCAPE , TAP_NATIVE , TAP_MRECT ,TWITTER_PROFILE , TWITTER_REPLIES , TWITTER_SEARCH , TWITTER_TIMELINE |
product_type required | The type of promoted product that this line item will contain. Type: enum Possible values: MEDIA , PROMOTED_ACCOUNT , PROMOTED_TWEETS |
start_time required | The time, expressed in ISO 8601, that the line item will begin serving. Type: string Example: 2017-07-05T00:00:00Z |
advertiser_domain sometimes required | The website domain for this advertiser, without the protocol specification. Note: Required when the line item’s placement is set to PUBLISHER_NETWORK .Type: string Example: x.com |
android_app_store_identifier sometimes required | The Google App Store identifier for promoted applications. Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier .Type: string Example: com.twitter.android |
bid_amount_local_micro sometimes required | The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. Note: Required if bid_strategy is set to either MAX or TARGET Note: Only values greater than zero are accepted. Type: long Example: 5500000 |
categories sometimes required | The relevant IAB categories for this advertiser. See GET iab_categories. Note: Required when the line item’s placement is set to PUBLISHER_NETWORK .Type: string Example: IAB3-1 |
ios_app_store_identifier sometimes required | The numeric portion of the Apple App Store identifier for promoted applications. Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier .Type: string Example: 333903271 |
primary_web_event_tag sometimes required | The identifier of the primary web event tag. Allows more accurate tracking of engagements for the campaign pertaining to this line item. Note: Required when the line item’s goal is set to WEBSITE_CONVERSIONS .Type: string Example: nvo4z |
advertiser_user_id optional | The X user identifier for the handle promoting a PREROLL_VIEWS ad. Only certain client applications may use this parameter.Type: string Example: 312226591 |
audience_expansion optional | Used to expand the reach of campaigns by targeting users similar to those already targeted. Note: By default, no expansion will be applied. Type: enum Possible values: BROAD , DEFINED , EXPANDED |
bid_strategy optional | The bidding mechanism.AUTO automatically optimizes bidding based on daily budget and campaign flight dates.MAX sets the maximum allowable bid and is not available when the objective is set to REACH or FOLLOWERS .TARGET attempts to make daily bid averages within 20% of the specified bid_amount_local_micro and is available when the objective is set to REACH , FOLLOWERS , OR WEBSITE_CLICKS .Note: If set to AUTO , bid_amount_local_micro will be ignored.Note: Default based on objective. Type: enum Possible values: AUTO , MAX , TARGET |
duration_in_days optional | The time period within which the frequency_cap is achieved.Type: int Possible values: 1 , 7 , 30 |
entity_status optional | The line item status. Type: enum Default: ACTIVE Possible values: ACTIVE , DRAFT , PAUSED |
frequency_cap optional | The maximum number of times an ad could be delivered to a user. Note: Only supported for REACH , ENGAGEMENTS , VIDEO_VIEWS , and PREROLL_VIEWS objectives.Type: int Example: 5 |
goal optional | The optimization setting to use with this line item. The APP_PURCHASES option is available for APP_INSTALL . The APP_CLICKS and APP_INSTALLS options are available for both APP_INSTALL and APP_ENGAGEMENTS objectives and may require using a supported MACT partner.The SITE_VISITS option is only available with the WEBSITE_CLICKS objective.Note: Default based on objective. Type: enum Possible values: APP_CLICKS , APP_INSTALLS , APP_PURCHASES ,ENGAGEMENT , FOLLOWERS , LINK_CLICKS , MAX_REACH , PREROLL , PREROLL_STARTS , REACH_WITH_ENGAGEMENT , SITE_VISITS , VIDEO_VIEW , VIEW_3S_100PCT , VIEW_6S , VIEW_15S , WEBSITE_CONVERSIONS |
name optional | The name for the line item. Type: string Example: demo Min, Max length: 1 , 255 |
pay_by optional | The unit to charge this line item by. This setting can only be modified for line items using the APP_INSTALLS objective.Note: The default pay_by is automatically set based upon the campaign objective and line item’s bid unit.The APP_INSTALLS goal supports both APP_CLICK and IMPRESSION values. IMPRESSION is the default value.The LINK_CLICKS goal supports both LINK_CLICK and IMPRESSION values. IMPRESSION is the default value but is not supported when setting TARGET for bid_strategy .The SITE_VISITS goal supports IMPRESSION values.Type: enum Possible values: APP_CLICK , IMPRESSION , LINK_CLICK |
standard_delivery optional | Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Only available when budget_optimization is set to LINE_ITEM for the parent campaignType: boolean Default: true Possible values: true , false |
total_budget_amount_local_micro optional | The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: 37500000 |
daily_budget_amount_local_micro sometimes required | The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Only available when budget_optimization is set to LINE_ITEM for the parent campaignNote: This should be less than or equal to the total_budget_amount_local_micro .Type: long Example: 5500000 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?campaign_id=hwtq0&objective=ENGAGEMENTS&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&bid_amount_local_micro=3210000&entity_status=PAUSED&daily_budget_amount_local_micro=1000000&start_time=2022-06-15
Example Response
Content-Type
of application/json
is required.errors
object.operation_errors
object.https://ads-api.x.com/12/batch/accounts/:account_id/line_items
Parameters
Name | Description |
---|---|
operation_type required | The per item operation type being performed. Type: enum Possible values: Create , Delete , Update |
params required | A JSON object containing all the parameters for the line item objects. For a list of required and optional line item parameters, see here. |
POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/line_items
https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id
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 |
line_item_id required | A reference to the line item you are operating with in the request. Type: string Example: 8v7jo |
advertiser_domain optional | The website domain for this advertiser, without the protocol specification. Note: Required when the line item’s placement is set to PUBLISHER_NETWORK .Type: string Example: x.com |
advertiser_user_id optional | The Twitter user identifier for the handle promoting a PREROLL_VIEWS ad. Only certain client applications may use this parameter.Type: string Example: 312226591 |
android_app_store_identifier optional | The Google App Store identifier for the promoted application. Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier .Type: string Example: com.twitter.android |
audience_expansion optional | Used to expand the reach of campaigns by targeting users similar to those already targeted. Type: enum Possible values: BROAD , DEFINED , EXPANDED |
bid_amount_local_micro optional | The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. Note: Required if bid_strategy is set to either MAX or TARGET Note: Only values greater than zero are accepted. Type: long Example: 140000 |
bid_strategy optional | The bidding mechanism.AUTO automatically optimizes bidding based on daily budget and campaign flight dates.MAX sets the maximum allowable bid and is not available when the objective is set to REACH or FOLLOWERS .TARGET attempts to make daily bid averages within 20% of the specified bid_amount_local_micro and is available when the objective is set to REACH or WEBSITE_CLICKS .Note: If set to AUTO , bid_amount_local_micro will be ignored.Note: Default based on objective. Type: enum Possible values: AUTO , MAX , TARGET |
categories optional | The relevant IAB categories for this advertiser. See GET iab_categories. Note: Required when the line item’s placement is set to PUBLISHER_NETWORK .Type: string Example: IAB3-1 |
duration_in_days optional | The time period within which the frequency_cap is achieved.Type: int Possible values: 1 , 7 , 30 |
entity_status optional | The line item status. Type: enum Possible values: ACTIVE , PAUSED |
end_time optional | The time, expressed in ISO 8601, that the line item will stop serving. Type: string Example: 2017-10-05T00:00:00Z |
frequency_cap optional | The maximum number of times an ad could be delivered to a user. Note: Only supported for REACH , ENGAGEMENTS , VIDEO_VIEWS , and PREROLL_VIEWS objectives.Type: int Example: 5 |
goal optional | The optimization setting to use with this line item. The APP_PURCHASES option is available for APP_INSTALL . The APP_CLICKS and APP_INSTALLS options are available for APP_INSTALL and APP_ENGAGEMENTS and may require using a supported MACT partner.Note: Default based on objective. Type: enum Possible values: APP_CLICKS , APP_INSTALLS , APP_PURCHASES , ENGAGEMENT , FOLLOWERS , LINK_CLICKS , MAX_REACH , PREROLL , PREROLL_STARTS , REACH_WITH_ENGAGEMENT , VIDEO_VIEW , VIEW_3S_100PCT , VIEW_6S , VIEW_15S , WEBSITE_CONVERSIONS |
ios_app_store_identifier optional | The numeric portion of the Apple App Store identifier for promoted applications. Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier .Type: string Example: 333903271 |
name optional | The name for the line item. Type: string Example: demo |
pay_by optional | The unit to charge this line item by. This setting can only be modified for line items using the APP_INSTALLS objective.Note: The default pay_by is automatically set based upon the campaign objective and line item’s bid unit.The APP_INSTALLS goal supports both APP_CLICK and IMPRESSION values. IMPRESSION is the default value.The LINK_CLICKS goal supports both LINK_CLICK and IMPRESSION values. IMPRESSION is the default value but is not supported when setting TARGET for bid_strategy .The SITE_VISITS goal supports IMPRESSION values.Type: enum Possible values: APP_CLICK , IMPRESSION , LINK_CLICK |
start_time optional | The time, expressed in ISO 8601, that the line item will begin serving. Type: string Example: 2017-07-05T00:00:00Z |
total_budget_amount_local_micro optional | The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: 37500000 |
daily_budget_amount_local_micro optional | The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Only available when budget_optimization is set to LINE_ITEM for the parent campaignNote: This should be less than or equal to the total_budget_amount_local_micro .Type: long Example: 5500000 |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9cqi0?bid_amount_local_micro=140000
Example Response
with_deleted=true
is specified in the request. These promoted_tweets are not actually deleted, though ("deleted": false
in the response). We do not cascade deletes.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id
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 |
line_item_id required | A reference to the line item you are operating with in the request. Type: string Exampple: 9f2ix |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9f2ix
Example Response
https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories
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 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories
Example Response
https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
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 |
line_item_curated_category_id required | A reference to the line item curated category you are operating with in the request. Type: string Example: 43853bhii885 |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories/yav
Example Response
https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories
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 |
curated_category_id required | A reference to the curated category entity you are operating with in the request. Type: string Example: 10miy |
line_item_id required | A reference to the line item you are operating with in the request. Type: string Example: 8v7jo |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories?line_item_id=iqwka&curated_category_id=9ddrgesiap6o
Example Response
https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
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 |
line_item_curated_category_id required | A reference to the line item curated category you are operating with in the request. Type: string Example: 1bzq3 |
curated_category_id optional | A reference to the curated category entity you are operating with in the request. Type: string Example: 10miy |
line_item_id optional | A reference to the line item you are operating with in the request. Type: string Example: 8v7jo |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq?curated_category_id=8tujl1p3yn0g
Example Response
https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
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 |
line_item_curated_category_id required | A reference to the line item curated category you are operating with in the request. Type: string Example: 1bzq3 |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq
Example Response
placement
and product_type
combinations.
Resource URL
https://ads-api.x.com/12/line_items/placements
Parameters
Name | Description |
---|---|
product_type optional | Scope the response to just the valid placements for the specified product type. Type: enum Possible values: MEDIA , PROMOTED_ACCOUNT , PROMOTED_TWEETS |
GET https://ads-api.x.com/12/line_items/placements?product_type=PROMOTED_ACCOUNT
Example Response
https://ads-api.x.com/12/accounts/:account_id/media_creatives
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 |
campaign_id optional | Scope the response to just the media creatives associated with the specified campaign. Type: string Example: 8gdx6 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
line_item_ids optional | Scope the response to just the media creatives associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8v7jo |
media_creative_ids optional | Scope the response to just the desired media creatives by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 1bzq3 |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3
Example Response
https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id
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 |
media_creative_id required | A reference to the media creative you are operating with in the request. Type: string Example: 43853bhii885 |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3
Example Response
creative_type
is PREROLL
) or image ads (such as BANNER
or INTERSTITIAL
) on the Twitter Audience Platform.
Note: In order to add media assets to the Account Media resource, use the POST accounts/:account_id/media_library endpoint.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/media_creatives
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 |
account_media_id required | A reference to the account media entity you are operating with in the request. Type: string Example: 10miy |
line_item_id required | A reference to the line item you are operating with in the request. Type: string Example: 8v7jo |
landing_url sometimes required | The URL of the website to direct a user to. This should only be used with TAP images (or “display creatives”). This value will be ignored if used with preroll assets. To associate a URL with a preroll asset, use the POST accounts/:account_id/preroll_call_to_actions endpoint. Note: Required when the line item’s objective is set to WEBSITE_CLICKS .Type: string Example: https://blog.x.com/ |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy
Example Response
https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id
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 |
media_creative_id required | A reference to the media creative you are operating with in the request. Type: string Example: 1bzq3 |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3
Example Response
user_id
in the response.
An HTTP 400 will be returned if none of the specified line items are configured to contain promoted accounts.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/promoted_accounts
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 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
line_item_ids optional | Scope the response to just the promoted accounts associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 9bpb2 |
promoted_account_ids optional | Scope the response to just the desired promoted accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 19pl2 |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2
Example Response
https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id
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 |
promoted_account_id required | A reference to the promoted account you are operating with in the request. Type: string Example: 19pl2 |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2
Example Response
user_id
) with the specified line item.
If the specified line item is not configured to be associated with Promoted Accounts, a HTTP 400 INCOMPATIBLE_LINE_ITEM
error will be returned. If the specified user is ineligible for promotion, a HTTP 400 will be returned and no users will be promoted. If the provided user is already promoted, the request will be ignored.
For more information on Promoted Accounts, see our campaign management page.
Note: It is not possible to update (PUT) promoted accounts entities.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/promoted_accounts
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 |
line_item_id required | A reference to the line item you are operating with in the request. Type: string Example: 9bpb2 |
user_id required | A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name. Type: long Example: 756201191646691328 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328
Example Response
https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id
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 |
promoted_account_id required | The identifier refers to the instance of a Promoted Account associated with a line item. Type: string Example: 19pl2 |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2
Example Response
tweet_id
values for each promoted_tweets object.
Note: When parent line items are deleted, promoted_tweets are only returned if with_deleted=true
is specified in the request. These promoted_tweets are not actually deleted, though ("deleted": false
in the response).
Resource URL
https://ads-api.x.com/12/accounts/:account_id/promoted_tweets
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 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
line_item_ids optional | Scope the response to just the Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 96uzp |
promoted_tweet_ids optional | Scope the response to just the desired promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 1efwlo |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo
Example Response
with_deleted=true
is specified in the request. These promoted_tweets are not actually deleted, though ("deleted": false
in the response).
Resource URL
https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id
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 |
promoted_tweet_id required | A reference to the promoted Tweet you are operating with in the request. Type: string Example: 1efwlo |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1efwlo
Example Response
PROMOTED_ACCOUNT
product type, associating a Tweet with the line_item
will add timeline placements on mobile in addition to the standard PROMOTED_ACCOUNT
placement.
Note: It is not possible to update (PUT) promoted Tweet entities.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/promoted_tweets
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 |
line_item_id required | A reference to the line item you are operating with in the request. Type: string Example: 8v7jo |
tweet_ids required | A comma-separated list of identifiers corresponding to specific Tweets. Up to 50 IDs may be provided. Type: long Example: 822333526255120384 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384
Example Response
https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id
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 |
promoted_tweet_id required | The identifier refers to the instance of a Promoted Tweet associated with a line item. This comes from the id field from a response item to GET accounts/:account_id/promoted_tweets, not the tweet_id of the Tweet in question. Supplied within the resource’s path.Type: string Example: 1gp8a5 |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1gp8a5
Example Response
FULL
or RETWEETS_ONLY
. This controls the type of content that is allowed to be promoted by the account. Advertisers must obtain permission to promote another user’s content and contact Twitter to get them added to your account as a RETWEETS_ONLY
promotable user.
Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you’d like to promote. You can use the POST accounts/:account_id/promoted-tweets endpoint to promote published Tweets and the POST accounts/:account_id/scheduled-promoted-tweets endpoint to promote another Twitter Ads account’s Scheduled Tweets.
You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the tweet_id
that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The tweet_id
that is returned corresponds to this new Tweet.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/promotable_users
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 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
promotable_user_ids optional | Scope the response to just the desired promotable users by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: l310s |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s
Example Response
FULL
or RETWEETS_ONLY
. This controls the type of content that is allowed to be promoted by the account.
Advertisers must obtain permission to promote another user’s content. Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you’d like to promote.
You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the tweet_id
that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The tweet_id
that is returned corresponds to this new Tweet.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/promotable_users/:promotable_user_id
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 |
promotable_user_id optional | A reference to the promotable user you are operating on within the request Type: string Example: l310s |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users/l310s
Example Response
https://ads-api.x.com/12/publishers
Parameters
No request parameters
Example Request
GET https://ads-api.x.com/12/publishers
Example Response
https://ads-api.x.com/5/accounts/:account_id/recommendations
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 |
GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations
Example Response
https://ads-api.x.com/5/accounts/:account_id/recommendations/:recommendation_id
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 |
recommendation_id required | A reference to the recommendation ID you are operating within the request Type: string Example: 62ce8zza1q0w |
GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations/62ce8zza1q0w
Example Response
https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets
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 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
line_item_ids optional | Scope the response to just the scheduled Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8xdpe |
scheduled_promoted_tweet_ids optional | Scope the response to just the desired scheduled promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 1xboq |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?scheduled_promoted_tweet_ids=1xboq
Example Response
https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id
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 |
scheduled_promoted_tweet_id required | A reference to the scheduled promoted Tweet you are operating with in the request. Type: string Example: 1xboq |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xboq
Example Response
https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets
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 |
line_item_id required | A reference to the line item you are operating with in the request. Type: string Example: 8xdpe |
scheduled_tweet_id required | A reference to the scheduled Tweet you are operating with in the request. Type: long Example: 870358555227860992 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?line_item_id=8xdpe&scheduled_tweet_id=870358555227860992
Example Response
scheduled_promoted_tweets
can only be deleted before the scheduled Tweet’s scheduled_at
time.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id
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 |
scheduled_promoted_tweet_id required | A reference to the scheduled promoted Tweet you are operating with in the request. This is the id attribute from a GET accounts/:account_id/scheduled_promoted_tweets response object.Type: string Example: 1xtfl |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xtfl
Example Response
https://ads-api.x.com/12/accounts/:account_id/targeting_criteria
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 |
line_item_ids required | Scope the response to just the targeting criteria under the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8u94t |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
lang optional | An ISO-639-1 language code. When passed, an additional localized_name attribute will be returned in the response for objects where a localized name is available.Type: string Example: fr |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
targeting_criterion_ids optional | Scope the response to just the desired targeting criteria by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: dpl3a6 |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_ids=8u94t
Example Response
https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id
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 |
targeting_criterion_id required | A reference to the targeting criterion you are operating with in the request. Type: string Example: eijd4y |
lang optional | An ISO-639-1 language code. When passed, an additional localized_name attribute will be returned in the response for objects where a localized name is available.Type: string Example: fr |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/eijd4y
Example Response
targeting_value
s for specific targeting types. We recommend that you refresh all data weekly, to ensure that you are working with the latest set of targeting type values. We change values and available targeting criteria from time to time; while the majority of these don’t change often, some do. There is no guarantee that these values will not change.
Use the BROAD_KEYWORD
, EXACT_KEYWORD
, PHRASE_KEYWORD
, or UNORDERED_KEYWORD
targeting types with the keywords specified in the targeting_value
. Exclude keywords by using the operator_type
request parameter set to NE
. See targeting keyword types for a detailed description of each type.
Note: It is only possible to target a single age bucket per line item.
Note: To target a Custom Audience, that audience must be targetable. i.e., targerable
must equal true
.
Note: When using targeting type TV_SHOW
, there must be at least one LOCATION
targeting criterion on the line item prior to setting the TV_SHOW
targeting and all LOCATION
must be within the same locale as the TV_SHOW
being targeted.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/targeting_criteria
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 |
line_item_id required | A reference to the line item you are operating with in the request. Type: string Example: 69ob |
operator_type required | Specify the relationship that the targeting criterion should have. For example, to exclude keywords, use operator_type=NE .Type: enum Possible values: EQ , NE , GTE , LT |
targeting_type required | The type of targeting that will be applied to this line item. Possible non-keyword-based values include: AGE , DEVICE , EVENT , CAMPAIGN_ENGAGEMENT , CAMPAIGN_ENGAGEMENT_LOOKALIKE , CONVERSATION , ENGAGEMENT_TYPE , FOLLOWERS_OF_USER , GENDER , INTEREST , LANGUAGE , LIVE_TV_EVENT , LOCATION , NETWORK_ACTIVATION_DURATION , NETWORK_OPERATOR , PLATFORM , PLATFORM_VERSION , SIMILAR_TO_FOLLOWERS_OF_USER , TV_SHOW , USER_ENGAGEMENT , USER_ENGAGEMENT_LOOKALIKE , WIFI_ONLY Note: It is only possible to target a single AGE bucket per line item.Possible keyword-based values include: BROAD_KEYWORD , EXACT_KEYWORD , PHRASE_KEYWORD , UNORDERED_KEYWORD Possible custom audience values include: CUSTOM_AUDIENCE , CUSTOM_AUDIENCE_EXPANDED Possible installed app store category values: APP_STORE_CATEGORY , APP_STORE_CATEGORY_LOOKALIKE Possible Twitter Audience Platform (TAP) app exclusion: APP_LIST (may only be used with operator_type=NE ) |
targeting_value required | Specify which user, which interest, which location, which event, which platform, which platform version, which device, which keyword or phrase, which gender, which custom audience, which app store category, or which exclusion of an app list this targeting will be applied to, depending on the selected targeting_type. Type: string Example: 174958347 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology
Example Response
Content-Type
of application/json
is required.errors
object.operation_errors
object.https://ads-api.x.com/12/batch/accounts/:account_id/targeting_criteria
Parameters
Name | Description |
---|---|
operation_type required | The per item operation type being performed. Type: enum Possible values: Create , Delete |
params required | A JSON object containing all the parameters for the targeting criteria objects. For a list of required and optional targeting criteria parameters, see here. In addition, this endpoint supports an operator_type parameter that works in conjunction with certain targeting_type values. The possible values for this parameter are EQ for equal to, GTE for greater than or equal to, LT for less than, and NE for not equal to. |
POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/targeting_criteria
https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id
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 |
targeting_criterion_id required | A reference to the targeting criterion you are operating with in the request. Type: string Example: dpl3a6 |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/dpl3a6
Example Response
https://ads-api.x.com/12/targeting_criteria/app_store_categories
Parameters
Name | Description |
---|---|
q optional | An optional query to scope a targeting criteria. Omit this parameter to retrive all. Type: string Example: music |
os_type optional | Scope the results by a specific app store. Type: enum Possible values: ANDROID , IOS |
GET https://ads-api.x.com/12/targeting_criteria/app_store_categories?q=music&os_type=IOS
Example Response
https://ads-api.x.com/12/targeting_criteria/conversations
Parameters
Name | Description |
---|---|
conversation_type optional | An optional query to scope to a certain conversation type. Type: enum Possible values: ACTORS , ATHLETES , BOOK_GENRES , BOOKS , BRAND_CATEGORIES , BRANDS , CELEBRITIES , COACHES , DIGITAL_CREATORS , ENTERTAINMENT_BRANDS , ENTERTAINMENT_PERSONALITIES , FICTIONAL_CHARACTERS , JOURNALISTS , LIFESTYLES , MOVIE_GENRES , MOVIES , MUSIC_GENRES , MUSICIANS , NEWS_STORIES , NEWS , PERSONS , PLACES , PODCASTS , POLITICAL_AFFILIATIONS , POLITICIANS , PRODUCTS , RADIO_STATIONS , SPORTS_LEAGUES , SPORTS_PERSONALITIES , SPORTS_TEAMS , SPORTS , TRENDS , TV_SHOWS , VIDEO_GAME_PLATFORMS , VIDEO_GAME_PUBLISHERS , VIDEO_GAMES |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
GET https://ads-api.x.com/12/targeting_criteria/conversations?count=2
Example Response
https://ads-api.x.com/12/targeting_criteria/devices
Parameters
Name | Description |
---|---|
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
q optional | An optional query to scope a targeting criteria. Omit this parameter to retrive all. Type: string Example: apple |
GET https://ads-api.x.com/12/targeting_criteria/devices?count=2&q=iphone
Example Response
start_time
and end_time
values on this endpoint are represented in UTC±00:00, irrespective of the event’s locale and timezone. This design should be kept in mind when querying and interacting with event start_time
and end_time
values. For example, Independence Day for the US is represented as start_time=2017-07-04T00:00:00Z
and end_time=2017-07-05T00:00:00Z
in UTC±00:00, and thus avoids the issue of this holiday existing across multiple timezones within the US.
Resource URL
https://ads-api.x.com/12/targeting_criteria/events
Parameters
Name | Description |
---|---|
event_types required | An optional query to scope to certain event types. Type: enum Possible values: CONFERENCE , HOLIDAY , MUSIC_AND_ENTERTAINMENT , OTHER , POLITICS , RECURRING , SPORTS |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
country_codes optional | An optional query to scope a targeting criteria search to particular countries with the 2 letter ISO country code. If this parameter is not specified, all events are returned. Type: string |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
end_time optional | The time, expressed in ISO 8601, that the campaign will end. Type: string Example: 2017-10-05T00:00:00Z |
start_time optional | The time, expressed in ISO 8601, that the line item will begin serving. Note: Defaults to the current time. Type: string Example: 2017-07-05T00:00:00Z |
GET https://ads-api.x.com/12/targeting_criteria/events?count=1
Example Response
https://ads-api.x.com/12/targeting_criteria/interests
Parameters
Name | Description |
---|---|
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
q optional | An optional query to scope a targeting criteria. Omit this parameter to retrive all. Type: string Example: books |
GET https://ads-api.x.com/12/targeting_criteria/interests?q=books
Example Response
https://ads-api.x.com/12/targeting_criteria/languages
Parameters
Name | Description |
---|---|
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
q optional | An optional query to scope a targeting criteria. Omit this parameter to retrive all. Type: string Example: english |
GET https://ads-api.x.com/12/targeting_criteria/languages?q=english
Example Response
CITIES
enum with the location_type
request parameter.
To target Designated Market Areas (DMAs), use the METROS
enum.
Resource URL
https://ads-api.x.com/12/targeting_criteria/locations
Parameters
Name | Description |
---|---|
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
country_code optional | An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. Omit this parameter to retrieve results for all countries. Type: string Example: JP |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
location_type optional | Scope the results by a specific kind of location. More granular targeting than COUNTRIES may not be available in all locations.Type: enum Possible values: COUNTRIES , REGIONS , METROS , CITIES , POSTAL_CODES |
q optional | An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results. Type: string Example: New York |
GET https://ads-api.x.com/12/targeting_criteria/locations?location_type=CITIES&q=los angeles
Example Response
https://ads-api.x.com/12/targeting_criteria/network_operators
Parameters
Name | Description |
---|---|
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
country_code optional | An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. If this parameter is not specified only partner audiences for the United States are returned. Type: string Default: US |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
q optional | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results. Type: string Examples: Airpeak |
GET https://ads-api.x.com/12/targeting_criteria/network_operators?count=5&country_code=US
Example Response
https://ads-api.x.com/12/targeting_criteria/platform_versions
Parameters
Name | Description |
---|---|
q optional | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results. Type: string Examples: jelly bean |
GET https://ads-api.x.com/12/targeting_criteria/platform_versions
Example Response
https://ads-api.x.com/12/targeting_criteria/platforms
Parameters
Name | Description |
---|---|
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
q optional | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results. Type: string Examples: ios , blackberry |
lang optional | Using a ISO-639-1 language code. When passed, an additional localized_name attribute will be returned in the response. Type: int, string Example: fr |
GET https://ads-api.x.com/12/targeting_criteria/platforms
Example Response
https://ads-api.x.com/12/targeting_criteria/tv_markets
Parameters
None
Example Request
GET https://ads-api.x.com/12/targeting_criteria/tv_markets
Example Response
estimated_users
value of 1000
.
Note: TV channel and genre targeting options are no longer supported.
Resource URL
https://ads-api.x.com/12/targeting_criteria/tv_shows
Parameters
Name | Description |
---|---|
locale required | A required parameter that specifies the tv_market_locale to query for available TV shows. TV markets are queried based on locale returned from the GET targeting_criteria/tv_markets.Type: string Example: en-US |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 50 Min, Max: 1 , 50 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
q optional | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results. Type: string Examples: ios , blackberry |
GET https://ads-api.x.com/12/targeting_criteria/tv_shows?locale=en-US&q=news&count=1
Example Response
https://ads-api.x.com/12/accounts/:account_id/targeting_suggestions
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 authenticating user. Type: string Example: 18ce54d4x5t |
suggestion_type required | Specify the type of suggestions to return. Type: enum Possible values: KEYWORD , USER_ID |
targeting_values required | Comma separated collection of either keywords or user IDs used to seed the suggestions. Note: These two types of suggestions cannot be mixed. Example: 756201191646691328 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 30 Min, Max: 1 , 50 |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_suggestions?suggestion_type=KEYWORD&targeting_values=developers&count=2"
Example Response
https://ads-api.x.com/12/accounts/:account_id/tax_settings
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 |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings
Example Response
https://ads-api.x.com/12/accounts/:account_id/tax_settings
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 |
address_city optional | The city for the account owner’s address. Type: string Example: San Francisco |
address_country optional | The two-letter country code for the account owner’s address. Type: string Example: US |
address_email optional | The email associated with the account owner’s address. Type: string Example: api@mctestface.com |
address_first_name optional | The first name for the account owner’s address. Type: string Example: API |
address_last_name optional | The last name for the account owner’s address. Type: string Example: McTestface |
address_name optional | The company name for the account owner’s address. Type: string Example: ABC, Co. |
address_postal_code optional | The postal code for the account owner’s address. Type: string Example: 94102 |
address_region optional | The region for the account owner’s address. Type: string Example: California |
address_street1 optional | The street line for the account owner’s address. Type: string Example: 21 March St |
address_street2 optional | The second street line for the account owner’s address. Type: string Example: Suite 99 |
bill_to optional | The entity that is billed. Type: enum Possible values: ADVERTISER , AGENCY |
business_relationship optional | Whether the account is owned by the advertiser or by the agency. Type: enum Possible values: AGENCY , SELF |
client_address_city optional | The city for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: Toronto |
client_address_country optional | The two-letter country code for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: CA |
client_address_email optional | The email associated with the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: ads@brand.com |
client_address_first_name optional | The first name for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: Brand |
client_address_last_name optional | The last name for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: Advertiser |
client_address_name optional | The company name for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: Brand, Inc. |
client_address_postal_code optional | The postal code for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: M5H 2N2 |
client_address_region optional | The region for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: Ontario |
client_address_street1 optional | The street line for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: 280 Queen St W |
client_address_street2 optional | The second street line for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: The 6 |
invoice_jurisdiction optional | Invoice jurisdiction. Type: enum Possible values: LOI_SAPIN , NONE , NOT_SET |
tax_category optional | Whether the taxation should be individual or business. Type: enum Possible values: BUSINESS_NO_VAT , BUSINESS_WITH_VAT , INDIVIDUAL |
tax_exemption_id optional | VAT exemption ID. Type: sting Example: 12345 |
tax_id optional | VAT registration ID. Type: string Possible values: 67890 |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings?address_name=ABC, Co.
Example Response
https://ads-api.x.com/12/accounts/:account_id/tracking_tags
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 |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
line_item_ids optional | Scope the response to just the tracking tags associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 96uzp |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
tracking_tag_ids optional | Scope the response to just the desired tracking tags by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 3m82 |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?tracking_tag_ids=3m82
Example Response
https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id
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 |
tracking_tag_id required | A reference to the tracking tag you are operating with in the request. Type: string Example: 555j |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j
Example Response
https://ads-api.x.com/12/accounts/:account_id/tracking_tags
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 |
line_item_id required | A reference to the line item you are operating with in the request. Type: string Example: 8v7jo |
tracking_tag_type required | The type of tracking tag. Type: enum Possible value: IMPRESSION_TAG , CLICK_TRACKER |
tracking_tag_url required | The tracking tag url provided by the tracking partner. Type: string Example: https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309 |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?line_item_id=fdwcl&tracking_tag_type=IMPRESSION_TAG&tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309
Example Response
https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id
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 |
tracking_tag_url required | The tracking tag url provided by the tracking partner. Type: string Example: https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309 |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/3m82?tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309
Example Response
https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id
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 |
tracking_tag_id required | A reference to the tracking tag you are operating with in the request. Type: string Example: 555j |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j
Example Response
https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id
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 |
user_id required | A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name. Type: long Example: 756201191646691328 |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328
Example Response
https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
user_id required | A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name. Type: long Example: 756201191646691328 |
notification_email optional | Email to use for account notifications. Type: string Example: user@domain.com |
contact_phone optional | Contact phone number. Type: string Example: 202-555-0128 |
contact_phone_extension optional | Extension for contact contact_phone . Type: string Example: 1234 |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328?notification_email='user@domain.com'&subscribe_email_types=ACCOUNT_PERFORMANCE,PERFORMANCE_IMPROVEMENT"
Example Response