Documentation Index
Fetch the complete documentation index at: https://x-preview-mintlify-17c4c782.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
API Reference
This is the full technical reference. For an overview of campaigns, line items, budgeting, targeting concepts, and a step-by-step getting started guide, see the
Campaign Management Overview.
Accounts
GET accounts
Retrieve details for some or all advertising-enabled accounts the authenticating user has access to. Resource URLhttps://ads-api.x.com/12/accounts
Scope the response to just the desired account IDs by specifying a comma-separated list of identifiers.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
An optional query to scope resource by
name. Performs case-insensitive prefix matching.Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Include deleted results in your request.
Include the
Note: This parameter and
total_count response attribute.
Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET accounts/:account_id
Retrieve a specific account that the authenticating user has access to. Resource URLhttps://ads-api.x.com/12/accounts/:account_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t
Example Response
POST accounts
Note: SANDBOX ONLY Create an ads account in the sandbox environment.SANDBOX ONLY
https://ads-api-sandbox.x.com/12/accounts
Parameters
None
Example Request
POST https://ads-api-sandbox.x.com/12/accounts
Example Response
PUT accounts/:account_id
Updates the account name and/or industry type. Resource URLhttps://ads-api.x.com/12/accounts/:account_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
The name of the account.
Industry that the account is associated with.
Possible values:
Possible values:
AGENCY, BUSINESS_TO_BUSINESS, ONLINE_SERVICES, EDUCATION, FINANCIAL, HEALTH, GOVERNMENT, MEDIA, MOBILE, RESTAURANT, RETAIL, TECHNOLOGY, TRAVEL, OTHERPUT https://ads-api.x.com/12/accounts/18ce54d4x5t?name='API McTestface 2'&industry_type=TECHNOLOGY
Example Response
DELETE accounts/:account_id
SANDBOX ONLY
https://ads-api-sandbox.x.com/12/accounts/:account_id
Parameters
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
DELETE https://ads-api-sandbox.x.com/12/accounts/gq12fh
Example Response
Account Apps
Run in Postman ❯GET account_apps
Retrieve details for all mobile apps that are associated with the specified ad account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/account_apps
Parameters
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Specifies the number of records to try and retrieve per distinct request. Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Include deleted results in your request.
Include the
Note: This parameter and
total_count response attribute.
Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_apps
Example Response
Account History
GET accounts/:account_id/account_history
Retrieve a summary of changes made to theentity_id specified in the request.
This endpoint is currently in beta and requires allowlisting.
https://ads-api.x.com/12/accounts/:account_id/account_history
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
The entity type to retrieve data for.
Possible values:
Possible values:
CAMPAIGN, LINE_ITEM, PROMOTED_TWEET, TARGETING_CRITERIA, PROMOTED_ACCOUNTThe specific entity to retrieve data for.
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).
Note: Must be expressed in whole hours (0 minutes and 0 seconds).
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).
Note: Must be expressed in whole hours (0 minutes and 0 seconds).
Scopes the response to a specific user.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_history?entity_type=CAMPAIGN&entity_id=fc3h5&count=1
Example Response
Advertiser Business Categories
GET advertiser_business_categories
Request the valid advertiser businesscategories for Ad Groups (line_items) to describe an advertiser’s brand to publishers.
These categories apply only to
line_items with the PREROLL_VIEWS objective and are separate from the content_categories used for targeting criteria.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
Audience Estimate
POST accounts/:account_id/audience_estimateDetermine the approximate audience size of your campaigns.
This endpoint accepts an array of JSON objects containing 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. Requests must be HTTP POST with a JSON content body with aContent-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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
An array of targeting criteria objects. A list of required and optional targeting criteria parameters are available on the POST targeting criteria endpoint.
Specify the relationship that the targeting criterion should have. For example, to set negated targeting, use
Possible values:
operator_type=NE.Possible values:
EQ, NEPOST https://ads-api.x.com/12/accounts/18ce54d4x5t/audience_estimate
Authenticated User Access
GET accounts/:account_id/authenticated_user_access
Retrieve the permissions of the currently authenticated user (access_token) as they relate to the specified ads account. These permissions match those exposed on ads.x.com. Possible values include: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
Bidding Rules
GET bidding_rules
Retrieve the bidding rules for some or all currencies. The response will indicate the minimum and maximum CPE (cost-per-engagement) bids. While these bidding rules change rarely, it is suggested that your systems refresh from these endpoints at least monthly. Resource URLhttps://ads-api.x.com/12/bidding_rules
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.
GET https://ads-api.x.com/12/bidding_rules?currency=USD
Example Response
Campaigns
GET accounts/:account_id/campaigns
Retrieve details for some or all campaigns associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/campaigns
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Scope the response to just the desired campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
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.
An optional query to scope resource by
name.Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Include deleted results in your request.
Include draft campaigns results in your request.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2
Example Response
GET accounts/:account_id/campaigns/:campaign_id
Retrieve a specific campaign associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the campaign you are operating with in the request.
Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2
Example Response
POST accounts/:account_id/campaigns
Create a new campaign associated with the current account. Note: There is a default limit of 200 active campaigns per account. However, there is no limit to the number of inactive campaigns. This limit can be raised to 8,000 active campaigns. To enable the higher limit, the advertiser must make the request to their X Account Manager. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/campaigns
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
The identifier for the funding instrument to create the campaign under.
The name for the campaign. Maximum length: 255 characters.
Select the type of budget optimization to be applied.
Possible values:
Possible values:
CAMPAIGN, LINE_ITEMThe 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
Note: This should be less than or equal to the
total_budget_amount_local_micro and is required for most Funding Instrument types.The campaign status.
Possible values:
Possible values:
ACTIVE, DRAFT, PAUSEDThe booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters.
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.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.
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
POST batch/accounts/:account_id/campaigns
Allows the batch creation of new campaigns with a single request. Batch Requests- The current maximum batch size is 40.
- All parameters are sent in the request body and a
Content-Typeofapplication/jsonis required. - Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.
- Request-level errors (eg. max batch size exceeded) are shown in the response under the
errorsobject. - Item-level errors (eg. missing required campaign parameter) are shown in the response under the
operation_errorsobject.
https://ads-api.x.com/12/batch/accounts/:account_id/campaigns
The per item operation type being performed.
Possible values:
Possible values:
Create, Delete, UpdateA JSON object containing all the parameters for the campaign objects. For a list of required and optional campaign parameters, see the single POST endpoint above.
POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/campaigns
PUT accounts/:account_id/campaigns/:campaign_id
Update the specified campaign associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the campaign you are operating with in the request.
Select the type of budget optimization to be applied.
Possible values:
Possible values:
CAMPAIGN, LINE_ITEMThe 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
Note: This should be less than or equal to the
total_budget_amount_local_micro.The campaign status.
Possible values:
Possible values:
ACTIVE, PAUSEDThe name for the campaign. Maximum length: 255 characters.
The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters.
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.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.
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000
Example Response
DELETE accounts/:account_id/campaigns/:campaign_id
Delete the specified campaign belonging to the current account. Note: Deleting a campaign is not reversible and subsequent attempts to delete the resource will return HTTP 404. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the campaign you are operating with in the request.
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m
Example Response
Content Categories
GET content_categories
Request the valid contentcategories 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
Curated Categories
GET accounts/:account_id/curated_categories
Retrieve a list of available Curated Categories for the givencountry_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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
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.
Specifies a cursor to get the next page of results. See Pagination for more information.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories?country_codes=US
Example Response
GET accounts/:account_id/curated_categories/:curated_category_id
Retrieve details for a specificcurated_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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the Curated Category you are operating with in the request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories/9ddrgesiap6o
Example Response
Features
GET accounts/:account_id/features
Retrieve the collection of granted features accessible by this ads account. Features are indicated by a descriptive feature key and are only exposed on this endpoint if they are introduced in beta or an otherwise limited release and are available in the Ads API. Features that do not meet this criteria will not be exposed on this endpoint. Note: This endpoint serves to aid Ads API ecosystem development by improving visibility into client access to beta releases. API developers can not request access to features on behalf of an advertiser. These requests can only be made by the advertiser to their X account manager. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/features
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
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.
Possible values:
Note: Only the features that are accessible by this account will be included in the response.
Possible values:
REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, WEBSITE_CLICKS_CPM_BILLINGGET https://ads-api.x.com/12/accounts/18ce54d4x5t/features
Example Response
POST accounts/:account_id/features
SANDBOX ONLY Add a feature to a sandbox account. The up to date list of account features may be retrieved via the GET accounts/:account_id/features endpoint. Resource URLhttps://ads-api-sandbox.x.com/12/accounts/:account_id/features
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A comma-separated list of account features to add to the account.
Possible values:
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_CARDPOST https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=VALIDATED_AGE_TARGETING
Example Response
DELETE accounts/:account_id/features
SANDBOX ONLY Remove a feature from a sandbox account. The up to date list of account features may be retrieved via the GET accounts/:account_id/features endpoint. Resource URLhttps://ads-api-sandbox.x.com/12/accounts/:account_id/features
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A comma-separated list of account features to remove from the account.
Possible values:
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_CARDDELETE https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=PREROLL_VIEWS_OBJECTIVE
Example Response
Funding Instruments
GET accounts/:account_id/funding_instruments
Retrieve details for some or all funding instruments associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/funding_instruments
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Specifies the number of records to try and retrieve per distinct request. Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
Scope the response to just the desired funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Include deleted results in your request.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments
Example Response
GET accounts/:account_id/funding_instruments/:funding_instrument_id
Retrieve a specific funding instrument associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/funding_instruments/:id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the funding instrument you are operating with in the request.
Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments/lygyi
Example Response
POST accounts/:account_id/funding_instruments
SANDBOX ONLY Create a funding instrument in the sandbox environment. There is no risk of incurring costs while using a sandbox funding instrument. Resource URLhttps://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
The date for the funding instrument to become active and usable, expressed in ISO 8601.
The type of funding instrument to create.
Possible values:
Possible values:
AGENCY_CREDIT_LINE, CREDIT_CARD, CREDIT_LINE, INSERTION_ORDER, PARTNER_MANAGEDThe total credit available against this funding instrument.
Note: Only applicable to some funding instrument types.
Note: Only applicable to some funding instrument types.
The total budget amount allocated to this funding instrument.
Note: Only applicable to some funding instrument types.
Note: Only applicable to some funding instrument types.
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
DELETE accounts/:account_id/funding_instruments/:funding_instrument_id
SANDBOX ONLY Delete a funding instrument in the sandbox environment. Resource URLhttps://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments/:funding_instrument_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the funding instrument you are operating with in the request.
DELETE https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments/hxt82
Example Response
IAB Categories
GET iab_categories
Request the valid appcategories for ad groups (line_items).
Resource URL
https://ads-api.x.com/12/iab_categories
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of categories. See Pagination for more information.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/iab_categories?count=2
Example Response
Line Items
GET accounts/:account_id/line_items
Retrieve details for some or all line items associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_items
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
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.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
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.
Scope the response to just the desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
An optional query to scope resource by
name.Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Include deleted results in your request.
Include draft campaigns results in your request.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?line_item_ids=itttx
Example Response
GET accounts/:account_id/line_items/:line_item_id
Retrieve a specific line item associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the line item you are operating with in the request.
Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/itttx
Example Response
POST accounts/:account_id/line_items
Create a line item associated with the specified campaign belonging to the current account. All line items within a campaign must be of the sameproduct_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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
The identifier for the campaign to create the line item under.
The campaign objective for this line item.
Possible values:
Possible values:
APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKSThe placement location(s) for this line item to display in. Specify a comma-separated list of placement values.
Possible values:
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_TIMELINEThe type of promoted product that this line item will contain.
Possible values:
Possible values:
MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETSThe website domain for this advertiser, without the protocol specification.
Note: Required when the line item’s placement is set to
Note: Required when the line item’s placement is set to
PUBLISHER_NETWORK.The Google App Store identifier for promoted applications.
Note:
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.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
Note: Required if
bid_strategy is set to either MAX or TARGET. Only values greater than zero are accepted.The relevant IAB categories for this advertiser. See GET iab_categories.
Note: Required when the line item’s placement is set to
Note: Required when the line item’s placement is set to
PUBLISHER_NETWORK.The numeric portion of the Apple App Store identifier for promoted applications.
Note:
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.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
Note: Required when the line item’s goal is set to
WEBSITE_CONVERSIONS.The X user identifier for the handle promoting a
PREROLL_VIEWS ad. Only certain client applications may use this parameter.Used to expand the reach of campaigns by targeting users similar to those already targeted.
Note: By default, no expansion will be applied.
Possible values:
Note: By default, no expansion will be applied.
Possible values:
BROAD, DEFINED, EXPANDEDThe bidding mechanism.
Note: If set to
Note: Default based on objective.
Possible values:
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.
Possible values:
AUTO, MAX, TARGETThe time period within which the
Possible values:
frequency_cap is achieved.Possible values:
1, 7, 30The line item status.
Possible values:
Possible values:
ACTIVE, DRAFT, PAUSEDThe maximum number of times an ad could be delivered to a user.
Note: Only supported for
Note: Only supported for
REACH, ENGAGEMENTS, VIDEO_VIEWS, and PREROLL_VIEWS objectives.The optimization setting to use with this line item.
The
The
Note: Default based on objective.
Possible values:
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.
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_CONVERSIONSThe name for the line item.
Min, Max length: 1, 255
Min, Max length: 1, 255
The unit to charge this line item by. This setting can only be modified for line items using the
Note: The default
The
The
The
Possible values:
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.Possible values:
APP_CLICK, IMPRESSION, LINK_CLICKEnable 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 campaign.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.
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
Note: This should be less than or equal to the
budget_optimization is set to LINE_ITEM for the parent campaign.Note: This should be less than or equal to the
total_budget_amount_local_micro.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
POST batch/accounts/:account_id/line_items
Allows the batch creation of new line items with a single request. Batch Requests- The current maximum batch size is 40.
- All parameters are sent in the request body and a
Content-Typeofapplication/jsonis required. - Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.
- Request-level errors (eg. max batch size exceeded) are shown in the response under the
errorsobject. - Item-level errors (eg. missing required line item parameter) are shown in the response under the
operation_errorsobject.
https://ads-api.x.com/12/batch/accounts/:account_id/line_items
The per item operation type being performed.
Possible values:
Possible values:
Create, Delete, UpdateA JSON object containing all the parameters for the line item objects. For a list of required and optional line item parameters, see the single POST endpoint above.
POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/line_items
PUT accounts/:account_id/line_items/:line_item_id
Update the specified line item associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the line item you are operating with in the request.
The website domain for this advertiser, without the protocol specification.
Note: Required when the line item’s placement is set to
Note: Required when the line item’s placement is set to
PUBLISHER_NETWORK.The Twitter user identifier for the handle promoting a
PREROLL_VIEWS ad. Only certain client applications may use this parameter.The Google App Store identifier for the promoted application.
Note:
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.Used to expand the reach of campaigns by targeting users similar to those already targeted.
Possible values:
Possible values:
BROAD, DEFINED, EXPANDEDThe 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
Note: Required if
bid_strategy is set to either MAX or TARGET. Only values greater than zero are accepted.The bidding mechanism.
Note: If set to
Note: Default based on objective.
Possible values:
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.
Possible values:
AUTO, MAX, TARGETThe relevant IAB categories for this advertiser. See GET iab_categories.
Note: Required when the line item’s placement is set to
Note: Required when the line item’s placement is set to
PUBLISHER_NETWORK.The time period within which the
Possible values:
frequency_cap is achieved.Possible values:
1, 7, 30The line item status.
Possible values:
Possible values:
ACTIVE, PAUSEDThe maximum number of times an ad could be delivered to a user.
Note: Only supported for
Note: Only supported for
REACH, ENGAGEMENTS, VIDEO_VIEWS, and PREROLL_VIEWS objectives.The optimization setting to use with this line item. The
Note: Default based on objective.
Possible values:
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.
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_CONVERSIONSThe numeric portion of the Apple App Store identifier for promoted applications.
Note:
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.The name for the line item.
The unit to charge this line item by. This setting can only be modified for line items using the
Note: The default
The
The
The
Possible values:
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.Possible values:
APP_CLICK, IMPRESSION, LINK_CLICKThe 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.
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
Note: This should be less than or equal to the
budget_optimization is set to LINE_ITEM for the parent campaign.Note: This should be less than or equal to the
total_budget_amount_local_micro.PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9cqi0?bid_amount_local_micro=140000
Example Response
DELETE accounts/:account_id/line_items/:line_item_id
Delete the specified line item belonging to the current account. Note: Deleting a line item is not reversible and subsequent attempts to delete the resource will return HTTP 404. Note: When a line item is deleted, its child promoted_tweets are only returned in the GET accounts/:account_id/promoted_tweets and GET accounts/:account_id/promoted_tweets/:promoted_tweet_id endpoints ifwith_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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the line item you are operating with in the request.
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9f2ix
Example Response
Line Item Curated Categories
Additional details on usage can be found at the Video Views Pre-roll Objective GuideGET accounts/:account_id/line_item_curated_categories
Retrieve details for some or all line item curated categories associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Include deleted results in your request.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories
Example Response
GET accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
Retrieves details for a specific line item curated category associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the line item curated category you are operating with in the request.
Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories/yav
Example Response
POST accounts/:account_id/line_item_curated_categories
Associate a curated category object with the specified line item. Resource URLhttps://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
PUT accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
Update the specified line item curated category. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the line item curated category you are operating with in the request.
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 |
Example Request
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq?curated_category_id=8tujl1p3yn0g
Example Response
DELETE accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
Delete the specified line item curated category. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the line item curated category you are operating with in the request.
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq
Example Response
Line Item Placements
GET line_items/placements
Retrieve validplacement and product_type combinations.
Resource URL
https://ads-api.x.com/12/line_items/placements
Scope the response to just the valid placements for the specified product type.
Possible values:
Possible values:
MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETSGET https://ads-api.x.com/12/line_items/placements?product_type=PROMOTED_ACCOUNT
Example Response
Media Creatives
GET accounts/:account_id/media_creatives
Retrieve details for some or all media creatives associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/media_creatives
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Scope the response to just the media creatives associated with the specified campaign.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
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.
Scope the response to just the desired media creatives by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Include deleted results in your request.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3
Example Response
GET accounts/:account_id/media_creatives/:media_creative_id
Retrieves details for a specific media creative associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the media creative you are operating with in the request.
Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3
Example Response
POST accounts/:account_id/media_creatives
Associate an account media object with the specified line item. Use this endpoint to promote in-stream ads (when the account mediacreative_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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the account media entity you are operating with in the request.
A reference to the line item you are operating with in the request.
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
Note: Required when the line item’s objective is set to
WEBSITE_CLICKS.POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy
Example Response
DELETE accounts/:account_id/media_creatives/:media_creative_id
Delete the specified media creative belonging to the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the media creative you are operating with in the request.
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3
Example Response
Promoted Accounts
GET accounts/:account_id/promoted_accounts
Retrieve details for some or all promoted accounts associated with one or more line items under the current account. Use GET users/lookup to obtain user data for the user accounts identified byuser_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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
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.
Scope the response to just the desired promoted accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Include deleted results in your request.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2
Example Response
GET accounts/:account_id/promoted_accounts/:promoted_account_id
Retrieve a specific reference to an account associated with a line item under the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the promoted account you are operating with in the request.
Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2
Example Response
POST accounts/:account_id/promoted_accounts
Associate an account (user_id) with the specified line item.
If the specified line item is not configured to be associated with Promoted Accounts, an HTTP 400 INCOMPATIBLE_LINE_ITEM error will be returned. If the specified user is ineligible for promotion, an 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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the line item you are operating with in the request.
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.
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328
Example Response
DELETE accounts/:account_id/promoted_accounts/:promoted_account_id
Disassociate an account from the specified line item. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
The identifier refers to the instance of a Promoted Account associated with a line item.
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2
Example Response
Promoted Tweets
GET accounts/:account_id/promoted_tweets
Retrieve references to Tweets associated with line items under the current account. Use the GET accounts/:account_id/tweets endpoint to fetch the Tweet objects. Use thetweet_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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
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.
Scope the response to just the desired promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Include deleted results in your request.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo
Example Response
GET accounts/:account_id/promoted_tweets/:promoted_tweet_id
Retrieve a specific reference to a Tweet associated with a line item under the current account. Note: When parent line items are deleted, promoted_tweets are only returned ifwith_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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the promoted Tweet you are operating with in the request.
Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1efwlo
Example Response
POST accounts/:account_id/promoted_tweets
Associate one or more Tweets with the specified line item. Not all Tweets are appropriate for promotion, depending on the campaign objective. Please see Objective-based Campaigns for more information. When using thePROMOTED_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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the line item you are operating with in the request.
A comma-separated list of identifiers corresponding to specific Tweets. Up to 50 IDs may be provided.
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384
Example Response
DELETE accounts/:account_id/promoted_tweets/:promoted_tweet_id
Disassociate a Tweet from the specified line item. Note: A deleted promoted_tweets entity will be displayed as “Paused” in the ads.x.com UI. Similarly, “pausing” from the UI will disassociate the Tweet from its line item. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
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.DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1gp8a5
Example Response
Promotable Users
GET accounts/:account_id/promotable_users
Retrieve details for some or all promotable users associated with the current account. The promotable user type is eitherFULL 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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
Scope the response to just the desired promotable users by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Include deleted results in your request.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s
Example Response
GET accounts/:account_id/promotable_users/:promotable_user_id
Retrieve a specific promotable user associated with the current account. The promotable user type is eitherFULL 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
A reference to the promotable user you are operating on within the request.
Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users/l310s
Example Response
Publishers
GET publishers
Retrieve a list of Content Category publishers’ details Additional details can be found in the Video Views Preroll Objective Guide Resource URLhttps://ads-api.x.com/12/publishers
Parameters
No request parameters
Example Request
GET https://ads-api.x.com/12/publishers
Example Response
Recommendations
GET accounts/:account_id/recommendations
Status: Closed Beta Retrieve campaign recommendations associated with this ads account. Currently there is a limit of 1 recommendation per funding instrument. Resource URLhttps://ads-api.x.com/5/accounts/:account_id/recommendations
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations
Example Response
GET accounts/:account_id/recommendations/:recommendation_id
Status: Closed Beta Retrieve a specific campaign recommendation associated with this ads account. The campaign recommendation contains a full set of changes suggested for the campaign structure represented as an object tree. The response tree is intended to work in conjunction with the Batch API endpoints, but it can also be mapped to single update endpoints as appropriate (Create for POST, Update for PUT, Delete for DELETE). Resource URLhttps://ads-api.x.com/5/accounts/:account_id/recommendations/:recommendation_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the recommendation ID you are operating within the request.
GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations/62ce8zza1q0w
Example Response
Scheduled Promoted Tweets
GET accounts/:account_id/scheduled_promoted_tweets
Retrieve details for some or all scheduled promoted Tweets associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
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.
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.
Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Include deleted results in your request.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?scheduled_promoted_tweet_ids=1xboq
Example Response
GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id
Retrieve a specific scheduled promoted Tweet associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the scheduled promoted Tweet you are operating with in the request.
Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xboq
Example Response
POST accounts/:account_id/scheduled_promoted_tweets
Associate a scheduled Tweet with the specified line item. Note: It is not possible to update (PUT) scheduled promoted Tweet entities. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the line item you are operating with in the request.
A reference to the scheduled Tweet you are operating with in the request.
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?line_item_id=8xdpe&scheduled_tweet_id=870358555227860992
Example Response
DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id
Disassociate a scheduled Tweet from the specified line item. Note: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_promoted_tweets/:scheduled_promoted_tweet_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
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.DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xtfl
Example Response
Targeting Criteria
GET accounts/:account_id/targeting_criteria
Retrieve details for some or all of the targeting criteria associated with line items under the current account.The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
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.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
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.Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Scope the response to just the desired targeting criteria by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Include deleted results in your request.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_ids=8u94t
Example Response
GET accounts/:account_id/targeting_criteria/:targeting_criterion_id
Retrieve a specific targeting criterion associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the targeting criterion you are operating with in the request.
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.Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/eijd4y
Example Response
POST accounts/:account_id/targeting_criteria
See the Targeting Options page to findtargeting_values 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
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the line item you are operating with in the request.
Specify the relationship that the targeting criterion should have. For example, to exclude keywords, use
Possible values:
operator_type=NE.Possible values:
EQ, NE, GTE, LTThe type of targeting that will be applied to this line item.
Possible non-keyword-based values include:
Note: It is only possible to target a single
Possible keyword-based values include:
Possible custom audience values include:
Possible installed app store category values:
Possible Twitter Audience Platform (TAP) app exclusion:
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).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.
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology
Example Response
POST batch/accounts/:account_id/targeting_criteria
Allows the batch creation of new Targeting Criteria with a single request. Batch Requests- The current maximum batch size is 500.
- All parameters are sent in the request body and a
Content-Typeofapplication/jsonis required. - Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.
- Request-level errors (eg. max batch size exceeded) are shown in the response under the
errorsobject. - Item-level errors (eg. missing required Targeting Criteria parameter) are shown in the response under the
operation_errorsobject.
https://ads-api.x.com/12/batch/accounts/:account_id/targeting_criteria
The per item operation type being performed.
Possible values:
Possible values:
Create, DeleteA 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
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
DELETE accounts/:account_id/targeting_criteria/:targeting_criterion_id
Delete the specified targeting criterion belonging to the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the targeting criterion you are operating with in the request.
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/dpl3a6
Example Response
Targeting Options
- App Store Categories
- Conversation
- Devices
- Events
- Interests
- Languages
- Locations
- Network Operators
- Platform Versions
- Platforms
- TV Markets
- TV Shows
GET targeting_criteria/app_store_categories
Discover available app store category-based targeting criteria for Promoted Products. App store categories are available for the iOS App Store and the Google Play store only. Installed app category targeting allows targeting of users based on the categories of apps they have installed or have indicated interest in. Resource URLhttps://ads-api.x.com/12/targeting_criteria/app_store_categories
An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
Scope the results by a specific app store.
Possible values:
Possible values:
ANDROID, IOSGET https://ads-api.x.com/12/targeting_criteria/app_store_categories?q=music&os_type=IOS
Example Response
GET targeting_criteria/conversations
Discover available conversation-based targeting criteria for Promoted Products. Resource URLhttps://ads-api.x.com/12/targeting_criteria/conversations
An optional query to scope to a certain conversation type.
Possible values:
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_GAMESSpecifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
GET https://ads-api.x.com/12/targeting_criteria/conversations?count=2
Example Response
GET targeting_criteria/devices
Discover available device-based targeting criteria for Promoted Products. Device targeting is available for Promoted Tweets. Resource URLhttps://ads-api.x.com/12/targeting_criteria/devices
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
GET https://ads-api.x.com/12/targeting_criteria/devices?count=2&q=iphone
Example Response
GET targeting_criteria/events
Discover available event-based targeting criteria for Promoted Products. Only one event can be targeted per line item. Note: Events often exist across timezones, leading to complications when considering event times from cross-timezone perspectives. To simplify this, all eventstart_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
An optional query to scope to certain event types.
Possible values:
Possible values:
CONFERENCE, HOLIDAY, MUSIC_AND_ENTERTAINMENT, OTHER, POLITICS, RECURRING, SPORTSSpecifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
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.
Specifies a cursor to get the next page of results. See Pagination for more information.
The time, expressed in ISO 8601, that the line item will begin serving.
Note: Defaults to the current time.
Note: Defaults to the current time.
GET https://ads-api.x.com/12/targeting_criteria/events?count=1
Example Response
GET targeting_criteria/interests
Discover available interest-based targeting criteria for Promoted Products. Interests change infrequently, however we suggest you refresh this list at least once weekly. Resource URLhttps://ads-api.x.com/12/targeting_criteria/interests
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
GET https://ads-api.x.com/12/targeting_criteria/interests?q=books
Example Response
GET targeting_criteria/languages
Discover languages available for targeting. Resource URLhttps://ads-api.x.com/12/targeting_criteria/languages
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
GET https://ads-api.x.com/12/targeting_criteria/languages?q=english
Example Response
GET targeting_criteria/locations
Discover available location-based targeting criteria for Promoted Products. Geo-targeting is available for Promoted Accounts and Promoted Tweets at the country level, state/region level, city level, and postal code level. Postal code targeting must be used if you wish to retrieve analytics at the postal code level. Note: To retrieve specific targetable cities, such as San Francisco or New York, use theCITIES 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
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
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.
Specifies a cursor to get the next page of results. See Pagination for more information.
Scope the results by a specific kind of location. More granular targeting than
Possible values:
COUNTRIES may not be available in all locations.Possible values:
COUNTRIES, REGIONS, METROS, CITIES, POSTAL_CODESAn optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
GET https://ads-api.x.com/12/targeting_criteria/locations?location_type=CITIES&q=los angeles
Example Response
GET targeting_criteria/network_operators
Discover available network operator-based targeting criteria for Promoted Products. This endpoint enables you to lookup targetingable carriers, such as AT&T, Verizon, Sprint, T-Mobile, etc., in multiple countries. Resource URLhttps://ads-api.x.com/12/targeting_criteria/network_operators
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
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.
Specifies a cursor to get the next page of results. See Pagination for more information.
An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
GET https://ads-api.x.com/12/targeting_criteria/network_operators?count=5&country_code=US
Example Response
GET targeting_criteria/platform_versions
Discover available mobile OS version-based targeting criteria for Promoted Products. Platform version targeting is available for Promoted Accounts and Promoted Tweets. This allows targeting down to the point release of a mobile operating system version, such as Android 8.0 or iOS 10.0. Resource URLhttps://ads-api.x.com/12/targeting_criteria/platform_versions
An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
GET https://ads-api.x.com/12/targeting_criteria/platform_versions
Example Response
GET targeting_criteria/platforms
Discover available platform-based targeting criteria for Promoted Products. Resource URLhttps://ads-api.x.com/12/targeting_criteria/platforms
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
Using a ISO-639-1 language code. When passed, an additional localized_name attribute will be returned in the response.
GET https://ads-api.x.com/12/targeting_criteria/platforms
Example Response
GET targeting_criteria/tv_markets
Discover available TV markets where TV shows can be targeted. Returns markets by locale that can used to query the GET targeting_criteria/tv_shows endpoint. Resource URLhttps://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
GET targeting_criteria/tv_shows
Discover available TV show-based targeting criteria for Promoted Products. TV show targeting is available for Promoted Tweets in certain markets. See the GET targeting_criteria/tv_markets endpoint for available markets. Note: Any audience that contains fewer than 1,000 users will appear with anestimated_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
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.Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 50
Min: 1, Max: 50
Specifies a cursor to get the next page of results. See Pagination for more information.
An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
GET https://ads-api.x.com/12/targeting_criteria/tv_shows?locale=en-US&q=news&count=1
Example Response
Targeting Suggestions
GET accounts/:account_id/targeting_suggestions
Get up to 50 keyword or user targeting suggestions to complement your initial selection. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/targeting_suggestions
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Specify the type of suggestions to return.
Possible values:
Possible values:
KEYWORD, USER_IDComma separated collection of either keywords or user IDs used to seed the suggestions.
Note: These two types of suggestions cannot be mixed.
Note: These two types of suggestions cannot be mixed.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 50
Min: 1, Max: 50
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_suggestions?suggestion_type=KEYWORD&targeting_values=developers&count=2"
Example Response
Tax Settings
GET accounts/:account_id/tax_settings
Retrieve tax setting details associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/tax_settings
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings
Example Response
PUT accounts/:account_id/tax_settings
Update the tax settings for the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/tax_settings
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
The city for the account owner’s address.
The two-letter country code for the account owner’s address.
The email associated with the account owner’s address.
The first name for the account owner’s address.
The last name for the account owner’s address.
The company name for the account owner’s address.
The postal code for the account owner’s address.
The region for the account owner’s address.
The street line for the account owner’s address.
The second street line for the account owner’s address.
The entity that is billed.
Possible values:
Possible values:
ADVERTISER, AGENCYWhether the account is owned by the advertiser or by the agency.
Possible values:
Possible values:
AGENCY, SELFThe city for the advertiser’s address.
Set this when the ads account is owned by an agency.
Set this when the ads account is owned by an agency.
The two-letter country code for the advertiser’s address.
Set this when the ads account is owned by an agency.
Set this when the ads account is owned by an agency.
The email associated with the advertiser’s address.
Set this when the ads account is owned by an agency.
Set this when the ads account is owned by an agency.
The first name for the advertiser’s address.
Set this when the ads account is owned by an agency.
Set this when the ads account is owned by an agency.
The last name for the advertiser’s address.
Set this when the ads account is owned by an agency.
Set this when the ads account is owned by an agency.
The company name for the advertiser’s address.
Set this when the ads account is owned by an agency.
Set this when the ads account is owned by an agency.
The postal code for the advertiser’s address.
Set this when the ads account is owned by an agency.
Set this when the ads account is owned by an agency.
The region for the advertiser’s address.
Set this when the ads account is owned by an agency.
Set this when the ads account is owned by an agency.
The street line for the advertiser’s address.
Set this when the ads account is owned by an agency.
Set this when the ads account is owned by an agency.
The second street line for the advertiser’s address.
Set this when the ads account is owned by an agency.
Set this when the ads account is owned by an agency.
Invoice jurisdiction.
Possible values:
Possible values:
LOI_SAPIN, NONE, NOT_SETWhether the taxation should be individual or business.
Possible values:
Possible values:
BUSINESS_NO_VAT, BUSINESS_WITH_VAT, INDIVIDUALVAT exemption ID.
VAT registration ID.
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings?address_name=ABC, Co.
Example Response
Tracking Tags
GET accounts/:account_id/tracking_tags
Retrieve details for some or all tracking tags associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/tracking_tags
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 1000
Min: 1, Max: 1000
Specifies a cursor to get the next page of results. See Pagination for more information.
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.
Sorts by supported attribute in ascending or descending order. See Sorting for more information.
Scope the response to just the desired tracking tags by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Include deleted results in your request.
Include the
Note: This parameter and
total_count response attribute.Note: This parameter and
cursor are exclusive. Requests which include total_count will have lower rate limits (currently 200 per 15 minutes).GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?tracking_tag_ids=3m82
Example Response
GET accounts/:account_id/tracking_tags/:tracking_tag_id
Retrieve a specific tracking tag associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the tracking tag you are operating with in the request.
Include deleted results in your request.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j
Example Response
POST accounts/:account_id/tracking_tags
Associate a tracking tag with the specified line item. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/tracking_tags
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the line item you are operating with in the request.
The type of tracking tag.
Possible value:
Possible value:
IMPRESSION_TAG, CLICK_TRACKERThe tracking tag url provided by the tracking partner.
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
PUT accounts/:account_id/tracking_tags/:tracking_tag_id
Associate a tracking tag with the specified line item. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
The tracking tag url provided by the tracking partner.
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
DELETE accounts/:account_id/tracking_tags/:tracking_tag_id
Disassociate a tracking tag from the specified line item. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
A reference to the tracking tag you are operating with in the request.
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j
Example Response
User Settings
(https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87)GET accounts/:account_id/user_settings/:user_id
Retrieves user settings. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
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.
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328
Example Response
PUT accounts/:account_id/user_settings/:user_id
Updates user settings. Requires user context. Not accessible by account admins. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
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.
Email to use for account notifications.
Contact phone number.
Extension for contact
contact_phone.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