Campaign Management API Reference

Complete reference for all Campaign Management endpoints in the X Ads API — Accounts, Campaigns, Line Items, Funding Instruments, Targeting Criteria, Placements, Content Categories, and related objects.

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 URL

https://ads-api.x.com/12/accounts

Parameters

Name	Description
account_ids optional	Scope the response to just the desired account IDs by specifying a comma-separated list of identifiers. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
q optional	An optional query to scope resource by name. Note: This performs case-insensitive prefix matching. Type: string Min, Max length: 1, 255
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts?account_ids=18ce54d4x5t

Example Response

       {
         "request": {
           "params": {
             "account_ids": [
               "18ce54d4x5t"
             ]
           }
         },
         "next_cursor": null,
         "data": [
           {
             "name": "API McTestface",
             "business_name": null,
             "timezone": "America/Los_Angeles",
             "timezone_switch_at": "2016-07-21T07:00:00Z",
             "id": "18ce54d4x5t",
             "created_at": "2016-07-21T22:42:09Z",
             "updated_at": "2017-07-06T16:51:04Z",
             "business_id": null,
             "approval_status": "ACCEPTED",
             "deleted": false
           }
         ]
       }

GET accounts/:account_id

Retrieve a specific account that the authenticating user has access to.

Resource URL

https://ads-api.x.com/12/accounts/:account_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t

Example Response

       {
         "request": {
           "params": {
             "account_id": "18ce54d4x5t"
           }
         },
         "data": {
           "name": "API McTestface",
           "business_name": null,
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": "2016-07-21T07:00:00Z",
           "id": "18ce54d4x5t",
           "created_at": "2016-07-21T22:42:09Z",
           "updated_at": "2017-07-06T16:51:04Z",
           "industry_type": "TRAVEL",
           "business_id": null,
           "approval_status": "ACCEPTED",
           "deleted": false
         }
       }

POST accounts

Note: SANDBOX ONLY

Create an ads account in the sandbox environment.

Resource URL

https://ads-api-sandbox.x.com/12/accounts

Parameters

None

Example Request

POST https://ads-api-sandbox.x.com/12/accounts

Example Response

       {
         "request": {
           "params": {}
         },
         "next_cursor": null,
         "data": [
           {
             "name": "Sandbox account",
             "business_name": null,
             "timezone": "America/Los_Angeles",
             "timezone_switch_at": null,
             "id": "gq12fh",
             "created_at": "2016-07-18T23:02:20Z",
             "updated_at": "2016-07-18T23:02:20Z",
             "business_id": null,
             "approval_status": "ACCEPTED",
             "deleted": false
           }
         ]
       }

PUT accounts/:account_id

Updates the account name and/or industry type.

Resource URL

https://ads-api.x.com/12/accounts/:account_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
name optional	The name of account. Type: string Example: API McTestface
industry_type optional	Industry that the account is associated with. Type: string Possible values: AGENCY, BUSINESS_TO_BUSINESS, ONLINE_SERVICES, EDUCATION, FINANCIAL, HEALTH, GOVERNMENT, MEDIA, MOBILE, RESTAURANT, RETAIL, TECHNOLOGY, TRAVEL, OTHER

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t?name='API McTestface 2'&industry_type=TECHNOLOGY

Example Response

       {
         "request": {
           "params": {
             "account_id": "18ce54d4x5t"
             "name"": "API McTestface 2",
             "industry_type": "TECHNOLOGY"
           }
         },
         "data": {
           "name": "API McTestface 2",
           "business_name": null,
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": "2016-07-21T07:00:00Z",
           "id": "18ce54d4x5t",
           "created_at": "2016-07-21T22:42:09Z",
           "updated_at": "2017-07-06T16:51:04Z",
           "industry_type": "TECHNOLOGY",
           "business_id": null,
           "approval_status": "ACCEPTED",
           "deleted": false
         }
       }

DELETE accounts/:account_id

Note: SANDBOX ONLY

Delete an ads account in the sandbox environment.

Resource URL

https://ads-api-sandbox.x.com/12/accounts/:account_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t

Example Request

DELETE https://ads-api-sandbox.x.com/12/accounts/gq12fh

Example Response

       {
         "data": {
           "name": "Sandbox account",
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": null,
           "id": "gq12fh",
           "created_at": "2016-07-18T23:02:20Z",
           "updated_at": "2017-08-23T18:21:10Z",
           "approval_status": "ACCEPTED",
           "deleted": true
         },
         "request": {
           "params": {
             "account_id": "gq12fh"
           }
         }
       }

Account Apps

Run in Postman ❯

GET account_apps

Retrieve details for all mobile apps that are associated with the specified ad account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/account_apps

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_apps

Example Response

       {
         "request": {
           "params": {
             "account_ids": [
               "18ce54d4x5t"
             ]
           }
         },
         "next_cursor": null,
         "data": [
          {
            "app_store_identifier": "com.twitter.android",
            "conversion_tracking_enabled": false,
            "deep_link_pattern": "twitter://",
            "id": "4x",
            "created_at": "2019-06-20T22:36:16Z",
            "updated_at": "2021-10-19T20:05:29Z",
            "os_type": "Android",
            "deleted": false
          }
         ]
       }

Account History

GET accounts/:account_id/account_history

Retrieve a summary of changes made to the entity_id specified in the request.

Note: This endpoint is currently in beta and requires allowlisting.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/account_history

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
entity_type required	The entity type to retrieve data for. Type: enum Example: PROMOTED_TWEET Possible values: CAMPAIGN, LINE_ITEM, PROMOTED_TWEET, TARGETING_CRITERIA, PROMOTED_ACCOUNT
entity_id required	The specific entitiy to retrieve data for. Type: string Example: 8u94t
start_time required	Scopes the retrieved data to the specified start time, expressed in ISO 8601. Note: Must be expressed in whole hours (0 minutes and 0 seconds). Type: string Example: 2017-05-19T07:00:00Z
end_time required	Scopes the retrieved data to the specified end time, expressed in ISO 8601. Note: Must be expressed in whole hours (0 minutes and 0 seconds). Type: string Example: 2017-05-26T07:00:00Z
user_id optional	Scopes the response to a specific user. Type: long Example: 3271358660

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_history?entity_type=CAMPAIGN&entity_id=fc3h5&count=1

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "CAMPAIGN",
          "entity_id": "fc3h5",
          "count": 1
        }
      },
      "next_cursor": "1r2407sb4lc",
      "data": [
        {
          "change_by": {
            "user_id": "982978172",
            "platform": "API_OTHER"
          },
          "changes": {},
          "change_time": "2021-04-02T20:55:42Z",
          "entity_id": "fc3h5",
          "entity": "CAMPAIGN",
          "entity_data": {
            "name": "test_campaign",
            "start_time": "2021-04-02T18:59:11Z",
            "purchase_order_number": null,
            "daily_budget_amount_local_micro": 100000000,
            "end_time": null,
            "duration_in_days": null,
            "standard_delivery": true,
            "total_budget_amount_local_micro": 100000000,
            "entity_status": "ACTIVE",
            "frequency_cap": null,
            "created_at": "2021-04-02T20:55:42Z",
            "updated_at": "2021-04-02T20:55:42Z",
            "deleted": false
          },
          "change_type": "CREATE"
        }
      ]
    }

Advertiser Business Categories

GET advertiser_business_categories

Request the valid advertiser business categories for Ad Groups (line_items) to describe an advertiser’s brand to publishers.

Note: These categories apply only to line_items with the PREROLL_VIEWS objective and are separate from the content_categories used for targeting criteria.

Each advertiser_business_categories represents a collection of IAB Categories. When creating an Ad Group with the PREROLL_VIEWS objective, one or two advertiser_business_categories must be set for the Ad Group. This can be done by setting the value of the categories request parameter on the line item endpoint to the set of corresponding iab_categories available through this endpoint.

Additional details can be found in the Video Views Preroll Objective Guide

Resource URL

https://ads-api.x.com/12/advertiser_business_categories

Parameters

No request parameters

Example Request

GET https://ads-api.x.com/12/advertiser_business_categories

Example Response

    {
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "id": "1jl",
          "name": "Consumer Packaged Goods",
          "iab_categories": [
            "IAB9-26",
            "IAB9-18",
            "IAB9-29",
            "IAB9-1",
            "IAB9-8",
            "IAB9-22",
            "IAB6",
            "IAB9-5",
            "IAB9-12",
            "IAB9-11",
            "IAB9-23",
            "IAB9-14",
            "IAB4",
            "IAB9-25",
            "IAB9-17",
            "IAB23",
            "IAB9-24",
            "IAB9-13",
            "IAB16",
            "IAB9-4",
            "IAB9-9",
            "IAB9-20",
            "IAB22",
            "IAB9-28",
            "IAB9-27",
            "IAB9-16",
            "IAB9-31",
            "IAB9-3",
            "IAB9-19",
            "IAB10",
            "IAB9-2",
            "IAB9-6",
            "IAB9-21",
            "IAB9-10",
            "IAB9-15"
          ]
        },
        {
          "id": "1jm",
          "name": "Health & Pharma",
          "iab_categories": [
            "IAB7"
          ]
        },
        {
          "id": "1jn",
          "name": "Alcohol",
          "iab_categories": [
            "IAB8-5",
            "IAB8-18"
          ]
        },
        {
          "id": "1jo",
          "name": "Dining",
          "iab_categories": [
            "IAB8-10",
            "IAB8-8",
            "IAB8-7",
            "IAB8-15",
            "IAB8-3",
            "IAB8-4",
            "IAB8-1",
            "IAB8-16",
            "IAB8-12",
            "IAB8-13",
            "IAB8-17",
            "IAB8-11",
            "IAB8-6",
            "IAB8-9",
            "IAB8-2",
            "IAB8-14"
          ]
        },
        {
          "id": "1jp",
          "name": "Financial Services",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ]
        },
        {
          "id": "1jq",
          "name": "Retail",
          "iab_categories": [
            "IAB18"
          ]
        },
        {
          "id": "1jr",
          "name": "Travel",
          "iab_categories": [
            "IAB20"
          ]
        },
        {
          "id": "1js",
          "name": "Gaming",
          "iab_categories": [
            "IAB9-30"
          ]
        },
        {
          "id": "1jt",
          "name": "Technology",
          "iab_categories": [
            "IAB19-22",
            "IAB19-13",
            "IAB19-4",
            "IAB19-33",
            "IAB19-26",
            "IAB19-3",
            "IAB19-16",
            "IAB19-9",
            "IAB19-32",
            "IAB19-25",
            "IAB19-30",
            "IAB19-36",
            "IAB19-21",
            "IAB5",
            "IAB19-12",
            "IAB19-28",
            "IAB19-17",
            "IAB19-8",
            "IAB19-7",
            "IAB19-24",
            "IAB15",
            "IAB19-11",
            "IAB19-31",
            "IAB19-20",
            "IAB19-15",
            "IAB19-1",
            "IAB19-35",
            "IAB19-29",
            "IAB19-34",
            "IAB19-23",
            "IAB19-2",
            "IAB19-5",
            "IAB19-14",
            "IAB19-27",
            "IAB19-10",
            "IAB19-19"
          ]
        },
        {
          "id": "1ju",
          "name": "Telecommunication",
          "iab_categories": [
            "IAB19-6",
            "IAB19-18"
          ]
        },
        {
          "id": "1jv",
          "name": "Auto",
          "iab_categories": [
            "IAB2"
          ]
        },
        {
          "id": "1jw",
          "name": "Media & Entertainment",
          "iab_categories": [
            "IAB14-8",
            "IAB14-4",
            "IAB1-5",
            "IAB14-7",
            "IAB1-7",
            "IAB17",
            "IAB14-3",
            "IAB1-1",
            "IAB12",
            "IAB1-6",
            "IAB25-1",
            "IAB1-2",
            "IAB14-2",
            "IAB14-6",
            "IAB1-3",
            "IAB1-4",
            "IAB14-5"
          ]
        },
        {
          "id": "1jx",
          "name": "Politics",
          "iab_categories": [
            "IAB11-4"
          ]
        },
        {
          "id": "1jy",
          "name": "Gambling",
          "iab_categories": [
            "IAB9-7"
          ]
        },
        {
          "id": "1jz",
          "name": "Dating",
          "iab_categories": [
            "IAB14-1"
          ]
        },
        {
          "id": "1k0",
          "name": "Non-Profit",
          "iab_categories": [
            "IAB11-1",
            "IAB11-2",
            "IAB11-3",
            "IAB11-5"
          ]
        }
      ]
    }

Audience Estimate

POST accounts/:account_id/audience_estimate

Determine 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 a Content-Type: application/json header.

Note: It is required that you specify at least one primary targeting criterion; you can see a list of all primary targeting criteria in our campaigns targeting page.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/audience_estimate

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
targeting_criteria required	A JSON object containing all the parameters for the targeting criteria objects. A list of required and optional targeting criteria parameters are available on the POST accounts/:account_id/targeting_criteria endpoint.
operator_type optional	Specify the relationship that the targeting criterion should have. For example, to set negated targeting, use operator_type=NE. Type: enum Possible values: EQ, NE Default: EQ

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/audience_estimate

    {
        "targeting_criteria": [
            {
                "targeting_type": "BROAD_KEYWORD",
                "targeting_value": "nba",
                "operator_type": "EQ"
            },
            {
                "targeting_type": "BROAD_KEYWORD",
                "targeting_value": "tech",
                "operator_type": "NE"
            },
            {
                "targeting_type": "LOCATION",
                "targeting_value": "96683cc9126741d1",
                "operator_type": "EQ"
            },
            {
                "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER",
                "targeting_value": "14230524"
            },
            {
                "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER",
                "targeting_value": "90420314"
            }
        ]
    }

Example Response

    {
      "request": {
        "params": {
          "targeting_criteria": null,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "audience_size": {
          "min": 38236294,
          "max": 42261167
        }
      }
    }

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 settings
• AD_MANAGER: Full access to modify campaigns and view stats, but cannot add or remove users or change settings
• CREATIVE_MANAGER: Access to modify creatives and view previews, but no access to create or modify campaigns
• CAMPAIGN_ANALYST: Access to view campaigns and view stats, but no access to create or modify campaigns
• ANALYST (“Organic Analyst” on ads.x.com): Access to view organic analytics and audience insights, but no access to create, modify, or view campaigns
• PARTNER_AUDIENCE_MANAGER: API-only access to view and modify data partner audiences, but no access to campaigns, creatives, or other audience types.

In addition, the 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

    {
      "data": {
        "user_id": "2417045708",
        "permissions": [
          "ACCOUNT_ADMIN",
          "TWEET_COMPOSER"
        ]
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      }
    }

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 URL

https://ads-api.x.com/12/bidding_rules

Parameters

Name	Description
currency optional	The type of a currency to filter results by, identified using ISO-4217. This is a three-letter string “USD” or “EUR”. Omit this parameter to retrieve all bidding rules associated with the authenticating user. Type: string Example: USD

Example Request

GET https://ads-api.x.com/12/bidding_rules?currency=USD

Example Response

    {
      "request": {
        "params": {
          "currency": "USD"
        }
      },
      "data_type": "bidding_rule",
      "data": [
        {
          "currency": "USD",
          "minimum_cpe_bid_local_micro": 10000,
          "maximum_cpe_bid_local_micro": 1000000000,
          "minimum_denomination": 10000
        }
      ],
      "total_count": 1
    }

Campaigns

GET accounts/:account_id/campaigns

Retrieve details for some or all campaigns associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
campaign_ids optional	Scope the response to just the desired campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8wku2
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Scope the response to just the campaigns under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: lygyi
q optional	An optional query to scope resource by name. Type: string Min, Max length: 1, 255
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_draft optional	Include draft campaigns results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "campaign_ids": [
            "8wku2"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "test",
          "budget_optimization": "CAMPAIGN",
          "reasons_not_servable": [
            "PAUSED_BY_ADVERTISER",
            "INCOMPLETE"
          ],
          "servable": false,
          "purchase_order_number": null,
          "effective_status": "UNKNOWN",
          "daily_budget_amount_local_micro": 10000000,
          "funding_instrument_id": "lygyi",
          "duration_in_days": null,
          "standard_delivery": false,
          "total_budget_amount_local_micro": null,
          "id": "8wku2",
          "entity_status": "PAUSED",
          "frequency_cap": null,
          "currency": "USD",
          "created_at": "2022-06-03T21:38:07Z",
          "updated_at": "2022-06-03T21:38:07Z",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/campaigns/:campaign_id

Retrieve a specific campaign associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
campaign_id required	A reference to the campaign you are operating with in the request. Type: string Example: 8wku2
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2

Example Response

    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 10000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8wku2",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:38:07Z",
        "deleted": false
      }
    }

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 URL

https://ads-api.x.com/12/accounts/:account_id/campaigns

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
funding_instrument_id required	The identifier for the funding instrument to create the campaign under. Type: string Example: lygyi
name required	The name for the campaign. Maximum length: 255 characters. Type: string Example: demo
budget_optimization optional	Select the type of budget optimization to be applied Type: enum Default: CAMPAIGN Possible values: CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro sometimes required	The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. Note: This should be less than or equal to the total_budget_amount_local_micro and is required for most Funding Insturment types. Type: long Example: 5500000
entity_status optional	The campaign status. Type: enum Default: ACTIVE Possible values: ACTIVE, DRAFT, PAUSED
purchase_order_number optional	The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters. Type: string Example: D00805843
standard_delivery optional	Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Only available when budget_optimization is set to CAMPAIGN. Type: boolean Default: true Possible values: true, false
total_budget_amount_local_micro optional	The total budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: 37500000

Example Request

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

    {
      "request": {
        "params": {
          "name": "demo",
          "budget_optimization": "CAMPAIGN",
          "daily_budget_amount_local_micro": 140000000,
          "funding_instrument_id": "lygyi",
          "standard_delivery": false,
          "entity_status": "PAUSED",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "demo",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "hwtbm",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:38:07Z",
        "deleted": false
      }
    }

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-Type of application/json is 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.

Batch Responses

Batch API responses return an ordered collection of items. Otherwise, they are identical in structure to their corresponding single-item endpoints.

Batch Errors

• Request-level errors (eg. max batch size exceeded) are shown in the response under the errors object.
• Item-level errors (eg. missing required campaign parameter) are shown in the response under the operation_errors object.

Resource URL

https://ads-api.x.com/12/batch/accounts/:account_id/campaigns

Parameters

Name	Description
operation_type required	The per item operation type being performed. Type: enum Possible values: Create, Delete, Update
params required	A JSON object containing all the parameters for the campaign objects. For a list of required and optional campaign parameters, see here.

Example Request

POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/campaigns

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"batch campaigns",
          "funding_instrument_id":"lygyi",
          "daily_budget_amount_local_micro":140000000,
          "entity_status":"PAUSED",
          "budget_optimization":"CAMPAIGN"
        }
      }
    ]

Example Response

    {
      "data": [
        {
          "name": "batch campaigns",
          "budget_optimization": "CAMPAIGN",
          "reasons_not_servable": [
            "PAUSED_BY_ADVERTISER",
            "INCOMPLETE"
          ],
          "servable": false,
          "purchase_order_number": null,
          "effective_status": "UNKNOWN",
          "daily_budget_amount_local_micro": 140000000,
          "funding_instrument_id": "lygyi",
          "duration_in_days": null,
          "standard_delivery": false,
          "total_budget_amount_local_micro": null,
          "id": "8yn7m",
          "entity_status": "PAUSED",
          "frequency_cap": null,
          "currency": "USD",
          "created_at": "2022-06-03T21:38:07Z",
          "updated_at": "2022-06-03T21:38:07Z",
          "deleted": false
        }
      ],
      "request": [
        {
          "params": {
            "name": "batch campaigns",
            "funding_instrument_id": "lygyi",
            "daily_budget_amount_local_micro": 140000000,
            "entity_status": "PAUSED",
            "budget_optimization":"CAMPAIGN",
            "account_id": "18ce54d4x5t"
          },
          "operation_type": "Create"
        }
      ]
    }

PUT accounts/:account_id/campaigns/:campaign_id

Update the specified campaign associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
campaign_id required	A reference to the campaign you are operating with in the request. Type: string Example: 8wku2
budget_optimization optional	Select the type of budget optimization to be applied Type: enum Default: CAMPAIGN Possible values: CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro optional	The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Note: This should be less than or equal to the total_budget_amount_local_micro. Type: long Example: 5500000
entity_status optional	The campaign status. Type: enum Possible values: ACTIVE, PAUSED
name optional	The name for the campaign. Maximum length: 255 characters. Type: string Example: demo
purchase_order_number optional	The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters. Type: string Example: D00805843
standard_delivery optional	Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Only available when budget_optimization is set to CAMPAIGN. Type: boolean Default: true Possible values: true, false
total_budget_amount_local_micro optional	The total budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: 140000000

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000

Example Response

    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "daily_budget_amount_local_micro": 140000000,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8wku2",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:53:54Z",
        "deleted": false
      }
    }

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 URL

https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
campaign_id required	A reference to the campaign you are operating with in the request. Type: string Exampple: 8yn7m

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m

Example Response

    {
      "request": {
        "params": {
          "campaign_id": "8yn7m",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [],
        "servable": null,
        "purchase_order_number": null,
        "effective_status": "RUNNING",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8yn7m",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:56:35Z",
        "deleted": true
      }
    }

Content Categories

GET content_categories

Request the valid content categories to be set as targeting_criteria for a line item.

Each content_category maps to one or more IAB Categories. This can be done by setting the targeting_type to IAB_CATEGORY on the batch targeting_critera endpoint to include the set of corresponding iab_categories returned by the content_categories request. Failure to do so will result in a validation error.

Publisher details for each of these content categories can be retrieved using the GET publishers endpoint.

Additional details can be found in the Video Views Pre-roll Objective Guide.

Resource URL

https://ads-api.x.com/12/content_categories

Parameters

No request parameters

Example Request

GET https://ads-api.x.com/12/content_categories

Example Response

    {
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "name": "Automotive (Cars, Trucks, Racing)",
          "id": "ru",
          "iab_categories": [
            "IAB2"
          ],
          "publishers_in_last_thirty_days": 12,
          "videos_monetized_in_last_thirty_days": 316
        },
        {
          "name": "Comedy",
          "id": "sk",
          "iab_categories": [
            "IAB1-4"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 174
        },
        {
          "name": "Digital Creators",
          "id": "sl",
          "iab_categories": [
            "IAB25-1"
          ],
          "publishers_in_last_thirty_days": 110,
          "videos_monetized_in_last_thirty_days": 1257
        },
        {
          "name": "Entertainment & Pop Culture",
          "id": "sm",
          "iab_categories": [
            "IAB1-1",
            "IAB1-2",
            "IAB1-3",
            "IAB1-5"
          ],
          "publishers_in_last_thirty_days": 120,
          "videos_monetized_in_last_thirty_days": 3482
        },
        {
          "name": "Financial & Business News",
          "id": "sn",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ],
          "publishers_in_last_thirty_days": 29,
          "videos_monetized_in_last_thirty_days": 1461
        },
        {
          "name": "Food & Drink",
          "id": "so",
          "iab_categories": [
            "IAB8-8",
            "IAB8-12",
            "IAB8-17",
            "IAB8-2",
            "IAB8-3",
            "IAB8-7",
            "IAB8-11",
            "IAB8-4",
            "IAB8-14",
            "IAB8-10",
            "IAB8-15",
            "IAB8-13",
            "IAB8-9",
            "IAB8-16",
            "IAB8-6",
            "IAB8-1"
          ],
          "publishers_in_last_thirty_days": 24,
          "videos_monetized_in_last_thirty_days": 516
        },
        {
          "name": "Lifestyle (Fashion, Travel, Wellness)",
          "id": "sp",
          "iab_categories": [
            "IAB16",
            "IAB9-21",
            "IAB9-4",
            "IAB9-25",
            "IAB9-8",
            "IAB4",
            "IAB9-3",
            "IAB9-15",
            "IAB7",
            "IAB6",
            "IAB9-11",
            "IAB9-16",
            "IAB9-7",
            "IAB9-20",
            "IAB9-24",
            "IAB9-17",
            "IAB9-12",
            "IAB9-31",
            "IAB9-27",
            "IAB10",
            "IAB9-10",
            "IAB9-23",
            "IAB9-6",
            "IAB9-18",
            "IAB9-13",
            "IAB9-1",
            "IAB9-28",
            "IAB20",
            "IAB9-5",
            "IAB9-26",
            "IAB22",
            "IAB23",
            "IAB9-9",
            "IAB9-22",
            "IAB18",
            "IAB9-2",
            "IAB9-19",
            "IAB9-14",
            "IAB9-29"
          ],
          "publishers_in_last_thirty_days": 67,
          "videos_monetized_in_last_thirty_days": 2412
        },
        {
          "name": "Music",
          "id": "sq",
          "iab_categories": [
            "IAB1-6"
          ],
          "publishers_in_last_thirty_days": 31,
          "videos_monetized_in_last_thirty_days": 518
        },
        {
          "name": "News & Current Events",
          "id": "sr",
          "iab_categories": [
            "IAB12",
            "IAB14"
          ],
          "publishers_in_last_thirty_days": 125,
          "videos_monetized_in_last_thirty_days": 5507
        },
        {
          "name": "Politics",
          "id": "s4",
          "iab_categories": [
            "IAB11"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 1402
        },
        {
          "name": "Science & Education",
          "id": "ss",
          "iab_categories": [
            "IAB5",
            "IAB15"
          ],
          "publishers_in_last_thirty_days": 7,
          "videos_monetized_in_last_thirty_days": 132
        },
        {
          "name": "Sports",
          "id": "se",
          "iab_categories": [
            "IAB17"
          ],
          "publishers_in_last_thirty_days": 403,
          "videos_monetized_in_last_thirty_days": 18281
        },
        {
          "name": "Technology",
          "id": "sg",
          "iab_categories": [
            "IAB19"
          ],
          "publishers_in_last_thirty_days": 13,
          "videos_monetized_in_last_thirty_days": 1089
        },
        {
          "name": "Television",
          "id": "sh",
          "iab_categories": [
            "IAB1-7"
          ],
          "publishers_in_last_thirty_days": 58,
          "videos_monetized_in_last_thirty_days": 1307
        },
        {
          "name": "Esports & Video Games",
          "id": "s0",
          "iab_categories": [
            "IAB9-30"
          ],
          "publishers_in_last_thirty_days": 109,
          "videos_monetized_in_last_thirty_days": 1844
        }
      ],
      "total_count": 15
    }

Curated Categories

GET accounts/:account_id/curated_categories

Retrieve a list of available Curated Categories for the given country_codes

Each curated_category is only available in specific countries specified by the country_codes in the response.

Additional details can be found in the Video Views Pre-roll Objective Guide.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/curated_categories

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
country_codes required	Scope the response to just the desired countries by specifying a comma-separated list of two letter ISO country codes. Up to 200 IDs may be provided. Type: string Example: US
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories?country_codes=US

Example Response

    {
      "request": {
        "params": {
          "country_codes": [
            "US"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "Basketball",
          "description": "Run next to the best of everyday basketball content including college teams, professional teams, and the top sports media handles sharing on and off-season basketball video.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "20265254",
            "378174762",
            "900368808",
            "18939563",
            "18371803",
            "18360370",
            "770658432928079872",
            "11026952",
            "37085464",
            "16212685",
            "57422635",
            "281669945",
            "7117962",
            "23065057",
            "41688179",
            "29779226",
            "900280416",
            "364460082",
            "902030382",
            "19409270",
            "19077044",
            "18139461",
            "14992591",
            "66753565",
            "667563",
            "16727749",
            "40941404",
            "18481113",
            "791598918",
            "16201775",
            "15900167",
            "45891626",
            "191894553",
            "2181233851",
            "34352904",
            "171483987",
            "454122399",
            "57415242",
            "19263978",
            "902089998",
            "423540866",
            "2715223320",
            "22185437",
            "17292143",
            "55590247",
            "66757066",
            "22642626",
            "41604618",
            "87275465",
            "22643259",
            "32414973",
            "73406718",
            "20346956",
            "413422891",
            "45412765",
            "19537303",
            "459511725",
            "30954864",
            "21308488",
            "18552281",
            "19924520",
            "24903350",
            "851142163",
            "26270913",
            "20444254",
            "26074296",
            "6395222",
            "15537451",
            "28672101",
            "38053254",
            "24925573",
            "19564719",
            "18164425",
            "22815383",
            "20196159"
          ],
          "id": "929wbl6ymlfk",
          "created_at": "2019-11-08T21:12:47Z",
          "updated_at": "2021-03-09T20:36:44Z",
          "videos_monetized_in_last_thirty_days": 2446
        },
        {
          "name": "Gaming Personalities",
          "description": "Run next to the best of everyday gaming content exclusively from a list of some of online gaming’s biggest and most loved digital creators.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "90779436",
            "268270621",
            "567167802",
            "246596682",
            "474919140",
            "284422688",
            "185909682",
            "4767225325",
            "2559865245",
            "186888760",
            "161418822",
            "141021153",
            "352881953",
            "1117931702",
            "146556805",
            "357294577",
            "234526497",
            "266687361",
            "214201922",
            "9451052",
            "2163885564",
            "2231422037",
            "116952434",
            "399909209",
            "15993650",
            "974356091193741312",
            "210839744",
            "2313002094",
            "159916388",
            "3258981481",
            "231992478",
            "182236262",
            "386884916",
            "22705686",
            "4140881832",
            "995979576",
            "2244953047",
            "311775629",
            "98821255",
            "2733210014",
            "2741078150"
          ],
          "id": "94ngssfrr01x",
          "created_at": "2019-12-02T20:45:12Z",
          "updated_at": "2021-03-09T20:18:13Z",
          "videos_monetized_in_last_thirty_days": 448
        },
        {
          "name": "Baseball",
          "description": "Run next to the best of everyday baseball content including college teams, professional teams, and the top sports media handles sharing major baseball coverage.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "22016177",
            "22798877",
            "52803520",
            "20710218",
            "423532170",
            "28603812",
            "41144996",
            "22819823",
            "39389304",
            "252273678",
            "123307490",
            "2319354187",
            "41488578",
            "37947138",
            "302066953",
            "159143990",
            "35006336",
            "53178109",
            "40918816",
            "39682297",
            "39397148",
            "39419180",
            "53197137",
            "52863923",
            "21407926",
            "31164229",
            "19607400",
            "39392910",
            "241544156",
            "43024351",
            "37837907",
            "165764237",
            "69117905",
            "87673496",
            "23043294",
            "52824038",
            "52861612",
            "33137450",
            "30008146",
            "39367703",
            "21436663",
            "188575356",
            "40931019",
            "41468683",
            "40927173",
            "172742915"
          ],
          "id": "9lav5usxfmdc",
          "created_at": "2020-05-18T20:20:27Z",
          "updated_at": "2021-03-09T20:37:46Z",
          "videos_monetized_in_last_thirty_days": 190
        },
        {
          "name": "Esports Teams",
          "description": "Run next to the programming from the world’s best esports teams, covering both in-event coverage and other year-round complimentary programming.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "759527448757215232",
            "61933836",
            "477213534",
            "907193396049182720",
            "895382891408089089",
            "862708050116976640",
            "115038550",
            "3182089458",
            "4131266472",
            "1145702070961496065",
            "2262070855",
            "920664872786059264",
            "1035653581683220481",
            "14229141",
            "1101275970995027968",
            "20734751",
            "1452520626",
            "720303639277928448",
            "2853641871",
            "912696400571486208",
            "874362688939413504",
            "286505380",
            "892808605170245632",
            "875087838613733376",
            "238431491",
            "867053221940011014",
            "964529942",
            "1172506293174710272",
            "535756639",
            "2255226817",
            "1100825469853696000",
            "1122713320086220803",
            "1124064709295128581",
            "899858978418642944",
            "864977592532688896",
            "864476897106898944",
            "862770685445361665",
            "257268592"
          ],
          "id": "9ys3jz3ktreo",
          "created_at": "2020-10-01T20:02:35Z",
          "updated_at": "2021-03-09T20:36:20Z",
          "videos_monetized_in_last_thirty_days": 169
        },
        {
          "name": "Football ",
          "description": "Run next to the best of everyday football content including college teams, professional teams, and the top sports media handles sharing on and off-season football video.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "21790466",
            "53103297",
            "23642374",
            "817416193854283776",
            "43403778",
            "24179879",
            "26813914",
            "36375662",
            "33587536",
            "180884045",
            "16332223",
            "27902825",
            "180503626",
            "44468807",
            "18336787",
            "818431566",
            "22146282",
            "31126587",
            "40358743",
            "35865630",
            "16347506",
            "72665816",
            "33583496",
            "389038362",
            "36155311",
            "227342532",
            "2151130166",
            "26791995",
            "44666348",
            "24109979",
            "31504542",
            "713143",
            "423536031",
            "25545388",
            "59471027",
            "706923475",
            "19383279",
            "8824902",
            "1655877529",
            "18734310",
            "240734425",
            "17076218",
            "47964412",
            "2802184770",
            "19426729",
            "56443153",
            "23508439",
            "25084916",
            "764347046",
            "19853312",
            "348590880"
          ],
          "id": "8tujg1lvi8sn",
          "created_at": "2019-08-15T20:48:51Z",
          "updated_at": "2021-03-09T20:34:13Z",
          "videos_monetized_in_last_thirty_days": 254
        },
        {
          "name": "Men’s Culture + Lifestyle",
          "description": "Run next to content from a set of handles curated based on their follower profiles to help you reach a majority male audience, including some of the top handles sharing technology, news, and lifestyle content.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "17764377",
            "61933836",
            "28370738",
            "3224616765",
            "22819823",
            "18927441",
            "734826612684783616",
            "14372486",
            "7157132",
            "15764136",
            "590316679",
            "7302282",
            "895014043932540928",
            "7517222",
            "3489420013",
            "14063426",
            "72665816",
            "214201922",
            "14980903",
            "22199141",
            "21272440",
            "25319414",
            "119593082",
            "4760694445",
            "765905855195803648",
            "238431491",
            "22178780",
            "241544156",
            "25093616",
            "16877611",
            "22146985",
            "368703433",
            "14342661",
            "415605847",
            "2181233851",
            "890891",
            "15764001",
            "614754689",
            "18479513",
            "23508439",
            "348590880"
          ],
          "id": "8tujj1ep7t34",
          "created_at": "2019-08-15T20:49:47Z",
          "updated_at": "2021-03-09T20:39:00Z",
          "videos_monetized_in_last_thirty_days": 1330
        },
        {
          "name": "Women’s Culture + Lifestyle",
          "description": "Run next to content from a set of handles curated based on their follower profiles to help you reach a majority female audience, including some of the top handles sharing pop culture, news, and lifestyle content.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "23482952",
            "20177423",
            "19074134",
            "15566901",
            "32469566",
            "19784831",
            "16145224",
            "16932962",
            "14934818",
            "29730065",
            "24190981",
            "30278532",
            "15846407",
            "24994219",
            "23993734",
            "40965341",
            "16312576",
            "75094638",
            "549673665",
            "18806753",
            "75306892",
            "1482663290",
            "31181674",
            "971407531972186112",
            "4020532937",
            "25087685",
            "22515362",
            "80943051",
            "19247844",
            "15279429",
            "16824090",
            "20710809",
            "979831113655996416",
            "32432308",
            "19472585",
            "25589776",
            "739963476370673665",
            "20188834",
            "926269727663673349"
          ],
          "id": "8tujl1p3yn0g",
          "created_at": "2019-08-15T20:50:24Z",
          "updated_at": "2021-03-09T20:17:53Z",
          "videos_monetized_in_last_thirty_days": 1365
        },
        {
          "name": "Light-Hearted",
          "description": "Run next to a list of handles curated for the volume of positive, feel-good content and conversation they’ve consistently generated on X.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "20177423",
            "22449367",
            "9695312",
            "19074134",
            "4805771380",
            "32469566",
            "1212860112047460352",
            "16402507",
            "16932962",
            "14934818",
            "17446621",
            "29730065",
            "15846407",
            "1604444052",
            "180066380",
            "16312576",
            "549673665",
            "18806753",
            "16211434",
            "545336345",
            "971407531972186112",
            "4020532937",
            "833612154",
            "22515362",
            "20710809",
            "32432308",
            "774311630",
            "3073349892",
            "926269727663673349"
          ],
          "id": "9fg8gmz96qdg",
          "created_at": "2020-03-20T19:37:44Z",
          "updated_at": "2021-03-09T19:57:40Z",
          "videos_monetized_in_last_thirty_days": 1395
        },
        {
          "name": "Soccer",
          "description": "Run next to the best of everyday soccer content including college teams, professional teams, and the top sports media handles sharing major soccer coverage.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "21677316",
            "20636347",
            "4704552148",
            "14573900",
            "22556296",
            "1415791555",
            "107146095",
            "17288520",
            "213474069",
            "17493398",
            "44990136",
            "452155423",
            "17744542",
            "16303450",
            "2841146601",
            "2413176055",
            "29739264",
            "38580532",
            "953476292913106945",
            "27092557",
            "86356439",
            "34613288",
            "3170659367",
            "119593082",
            "73412535",
            "627586654",
            "15891449",
            "23011345",
            "96951800",
            "15997022",
            "16960789",
            "21919642",
            "102965285",
            "17224076",
            "36432200",
            "1410055968"
          ],
          "id": "9ddrgesiap6o",
          "created_at": "2020-02-28T22:43:26Z",
          "updated_at": "2021-01-26T17:54:55Z",
          "videos_monetized_in_last_thirty_days": 421
        }
      ],
      "total_count": 9
    }

GET accounts/:account_id/curated_categories/:curated_category_id

Retrieve details for a specific curated_category_id

Each curated_category is only available in specific countries specified by the country_codes in the response.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/curated_categories/:curated_category_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
curated_category_id required	A reference to the Curated Category you are operating with in the request. Type: string Example: 9ddrgesiap6o

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories/9ddrgesiap6o

Example Response

    {
      "request": {
        "params": {
          "id": "9ddrgesiap6o",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "Soccer",
        "description": "Run next to the best of everyday soccer content including college teams, professional teams, and the top sports media handles sharing major soccer coverage.",
        "country_codes": [],
        "publisher_user_ids": [
          "21677316",
          "20636347",
          "4704552148",
          "14573900",
          "22556296",
          "1415791555",
          "107146095",
          "17288520",
          "213474069",
          "17493398",
          "44990136",
          "452155423",
          "17744542",
          "16303450",
          "2841146601",
          "2413176055",
          "29739264",
          "38580532",
          "953476292913106945",
          "27092557",
          "86356439",
          "34613288",
          "3170659367",
          "119593082",
          "73412535",
          "627586654",
          "15891449",
          "23011345",
          "96951800",
          "15997022",
          "16960789",
          "21919642",
          "102965285",
          "17224076",
          "36432200",
          "1410055968"
        ],
        "id": "9ddrgesiap6o",
        "created_at": "2020-02-28T22:43:26Z",
        "updated_at": "2021-01-26T17:54:55Z",
        "videos_monetized_in_last_thirty_days": 421
      }
    }

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 URL

https://ads-api.x.com/12/accounts/:account_id/features

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
feature_keys optional	An optional parameter that enables querying for a specific feature key. Requests may include multiple comma-separated keys. Note: Only the features that are accessible by this account will be included in the response. Type: enum Possible values: REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, WEBSITE_CLICKS_CPM_BILLING

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/features

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": [
        "CITY_TARGETING",
        "CONVERSATION_CARD",
        "PROMOTED_MEDIA_POLLS",
        "REACH_AND_FREQUENCY_ANALYTICS",
        "REACH_FREQUENCY_CAP",
        "UNIVERSAL_LOOKALIKE"
      ]
    }

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 URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/features

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: gq180y
feature_keys required	A comma-separated list of account features to add to the account. Type: enum Possible values: AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD

Example Request

POST https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=VALIDATED_AGE_TARGETING

Example Response

    {
      "request": {
        "params": {
          "account_id": "gq180y",
          "feature_keys": [
            "VALIDATED_AGE_TARGETING"
          ]
        }
      },
      "data": [
        "ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE",
        "AWARENESS_OBJECTIVE",
        "CPI_CHARGING",
        "EVENT_TARGETING",
        "INSTALLED_APP_CATEGORY_TARGETING",
        "MOBILE_CONVERSION_TRANSACTION_VALUE",
        "OPTIMIZED_ACTION_BIDDING",
        "VALIDATED_AGE_TARGETING",
        "VIDEO_APP_DOWNLOAD_CARD"
      ]
    }

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 URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/features

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: gq180y
feature_keys required	A comma-separated list of account features to remove from the account. Type: enum Possible values: AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD

Example Request

DELETE https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=PREROLL_VIEWS_OBJECTIVE

Example Response

    {
      "request": {
        "params": {
          "account_id": "gq180y",
          "feature_keys": [
            "PREROLL_VIEWS_OBJECTIVE"
          ]
        }
      },
      "data": [
        "CPI_CHARGING",
        "EVENT_TARGETING",
        "INSTALLED_APP_CATEGORY_TARGETING",
        "MOBILE_CONVERSION_TRANSACTION_VALUE",
        "OPTIMIZED_ACTION_BIDDING",
        "VIDEO_APP_DOWNLOAD_CARD"
      ]
    }

Funding Instruments

GET accounts/:account_id/funding_instruments

Retrieve details for some or all funding instruments associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/funding_instruments

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Scope the response to just the desired funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: lygyi
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "start_time": "2016-07-22T04:24:04Z",
          "description": "Visa ending in 0650",
          "credit_limit_local_micro": 200000000,
          "end_time": null,
          "id": "lygyi",
          "entity_status": "ACTIVE",
          "account_id": "18ce54d4x5t",
          "reasons_not_able_to_fund": [],
          "io_header": null,
          "currency": "USD",
          "funded_amount_local_micro": 645940000,
          "created_at": "2016-07-22T04:24:04Z",
          "type": "CREDIT_CARD",
          "able_to_fund": true,
          "updated_at": "2017-04-05T00:25:13Z",
          "credit_remaining_local_micro": null,
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/funding_instruments/:funding_instrument_id

Retrieve a specific funding instrument associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/funding_instruments/:id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
funding_instrument_id required	A reference to the funding instrument you are operating with in the request. Type: string Example: lygyi
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments/lygyi

Example Response

    {
      "request": {
        "params": {
          "funding_instrument_id": "lygyi",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "start_time": "2016-07-22T04:24:04Z",
        "description": "Visa ending in 0650",
        "credit_limit_local_micro": 200000000,
        "end_time": null,
        "id": "lygyi",
        "entity_status": "ACTIVE",
        "account_id": "18ce54d4x5t",
        "reasons_not_able_to_fund": [],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": 645940000,
        "created_at": "2016-07-22T04:24:04Z",
        "type": "CREDIT_CARD",
        "able_to_fund": true,
        "updated_at": "2017-04-05T00:25:13Z",
        "credit_remaining_local_micro": null,
        "deleted": false
      }
    }

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 URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: gq1844
currency required	The currency, expressed in ISO-4217. Type: string Example: USD
start_time required	The date for the funding instrument to become active and usable, expressed in ISO 8601. Type: string Example: 2017-05-19T07:00:00Z
type required	The type of funding instrument to create. Type: enum Possible values: AGENCY_CREDIT_LINE, CREDIT_CARD, CREDIT_LINE, INSERTION_ORDER, PARTNER_MANAGED
end_time sometimes required	The date for the funding instrument to become inactive, expressed in ISO 8601. Type: string Example: 2017-05-26T07:00:00Z
credit_limit_local_micro optional	The total credit available against this funding instrument. Note: Only applicable to some funding instrument types. Type: long Example: 37500000
funded_amount_local_micro optional	The total budget amount allocated to this funding instrument. Note: Only applicable to some funding instrument types. Type: long Example: 37500000

Example Request

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

    {
      "data": {
        "start_time": "2017-07-10T00:00:00Z",
        "description": "(no payment method has been set up yet)",
        "credit_limit_local_micro": null,
        "end_time": "2018-01-10T00:00:00Z",
        "id": "hxtet",
        "entity_status": "ACTIVE",
        "account_id": "gq1844",
        "reasons_not_able_to_fund": [],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": 140000000000,
        "created_at": "2017-09-09T05:23:28Z",
        "type": "INSERTION_ORDER",
        "able_to_fund": true,
        "updated_at": "2017-09-09T05:23:28Z",
        "credit_remaining_local_micro": null,
        "deleted": false
      },
      "request": {
        "params": {
          "start_time": "2017-07-10T00:00:00Z",
          "end_time": "2018-01-10T00:00:00Z",
          "account_id": "gq1844",
          "currency": "USD",
          "funded_amount_local_micro": 140000000000,
          "type": "INSERTION_ORDER"
        }
      }
    }

DELETE accounts/:account_id/funding_instruments/:funding_instrument_id

SANDBOX ONLY

Delete a funding instrument in the sandbox environment.

Resource URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments/:funding_instrument_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: gq1844
funding_instrument_id required	A reference to the funding instrument you are operating with in the request. Type: string Exampple: hxt82

Example Request

DELETE https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments/hxt82

Example Response

    {
      "data": {
        "start_time": "2017-08-30T19:23:47Z",
        "description": "(no payment method has been set up yet)",
        "credit_limit_local_micro": 500000000,
        "end_time": null,
        "id": "hxt82",
        "entity_status": "ACTIVE",
        "account_id": "gq1844",
        "reasons_not_able_to_fund": [
          "DELETED"
        ],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": null,
        "created_at": "2017-08-30T19:23:47Z",
        "type": "CREDIT_CARD",
        "able_to_fund": false,
        "updated_at": "2017-09-09T02:08:30Z",
        "credit_remaining_local_micro": null,
        "deleted": true
      },
      "request": {
        "params": {
          "funding_instrument_id": "hxt82",
          "account_id": "gq1844"
        }
      }
    }

IAB Categories

GET iab_categories

Request the valid app categories for ad groups (line_items).

Resource URL

https://ads-api.x.com/12/iab_categories

Parameters

Name	Description
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of categories. See Pagination for more information. Type: string Example: gc-ddf4a
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/iab_categories?count=2

Example Response

    {
      "data": [
        {
          "id": "IAB1",
          "parent_id": null,
          "name": "Arts & Entertainment"
        },
        {
          "id": "IAB1-1",
          "parent_id": "IAB1",
          "name": "Books & Literature"
        }
      ],
      "next_cursor": "uxa8",
      "request": {
        "params": {
          "count": 2
        }
      }
    }

Line Items

GET accounts/:account_id/line_items

Retrieve details for some or all line items associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
campaign_ids optional	Scope the response to just the line items under specific campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8gdx6
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
funding_instrument_ids optional	Scope the response to just the line items under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: lygyi
line_item_ids optional	Scope the response to just the desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8v7jo
q optional	An optional query to scope resource by name. Type: string Min, Max length: 1, 255
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_draft optional	Include draft campaigns results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?line_item_ids=itttx

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "line_item_ids": [
            "itttx"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "advertiser_user_id": "756201191646691328",
          "name": "li-18",
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": "2021-02-16T00:00:00Z",
          "bid_amount_local_micro": 320000,
          "advertiser_domain": null,
          "target_cpa_local_micro": null,
          "primary_web_event_tag": null,
          "goal": "ENGAGEMENT",
          "daily_budget_amount_local_micro": null,
          "product_type": "PROMOTED_TWEETS",
          "end_time": null,
          "funding_instrument_id": "lygyi",
          "bid_strategy": "MAX",
          "duration_in_days": null,
          "standard_delivery": null,
          "total_budget_amount_local_micro": null,
          "objective": "ENGAGEMENTS",
          "id": "itttx",
          "entity_status": "PAUSED",
          "automatic_tweet_promotion": null,
          "frequency_cap": null,
          "android_app_store_identifier": null,
          "categories": [],
          "currency": "USD",
          "pay_by": "ENGAGEMENT",
          "created_at": "2021-02-23T23:37:54Z",
          "ios_app_store_identifier": null,
          "updated_at": "2022-06-01T02:01:18Z",
          "campaign_id": "f4z6x",
          "creative_source": "MANUAL",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/line_items/:line_item_id

Retrieve a specific line item associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_id required	A reference to the line item you are operating with in the request. Type: string Example: 8v7jo
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/itttx

Example Response

    {
      "request": {
        "params": {
          "line_item_id": "itttx",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": "li-18",
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2021-02-16T00:00:00Z",
        "bid_amount_local_micro": 320000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": null,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "funding_instrument_id": "lygyi",
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": null,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "itttx",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2021-02-23T23:37:54Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-01T02:01:18Z",
        "campaign_id": "f4z6x",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

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 same product_type and objective.

When using the PROMOTED_ACCOUNT product type, associating a Tweet with the line_item will add timeline placements on mobile in addition to the standard PROMOTED_ACCOUNT placement.

Setting either android_app_store_identifier or ios_app_store_identifier will automatically add the targeting criteria for the line item matching the mobile app being promoted; for example, passing in ios_app_store_identifier would add PLATFORM targeting criteria for iOS.

Note: There is a limit of 100 line items per campaign and 256 active line items across all campaigns.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
campaign_id required	The identifier for the campaign to create the line item under. Type: string Example: 8slvg
end_time required	The time, expressed in ISO 8601, that the line item will stop serving. Type: string Example: 2017-10-05T00:00:00Z
objective required	The campaign objective for this line item. Type: enum Possible values: APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKS
placements required	The placement location(s) for this line item to display in. Specify a comma-separated list of placement values. Type: enum Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK, TAP_BANNER, TAP_FULL, TAP_FULL_LANDSCAPE, TAP_NATIVE, TAP_MRECT,TWITTER_PROFILE, TWITTER_REPLIES, TWITTER_SEARCH, TWITTER_TIMELINE
product_type required	The type of promoted product that this line item will contain. Type: enum Possible values: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS
start_time required	The time, expressed in ISO 8601, that the line item will begin serving. Type: string Example: 2017-07-05T00:00:00Z
advertiser_domain sometimes required	The website domain for this advertiser, without the protocol specification. Note: Required when the line item’s placement is set to PUBLISHER_NETWORK. Type: string Example: x.com
android_app_store_identifier sometimes required	The Google App Store identifier for promoted applications. Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier. Type: string Example: com.twitter.android
bid_amount_local_micro sometimes required	The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. Note: Required if bid_strategy is set to either MAX or TARGET Note: Only values greater than zero are accepted. Type: long Example: 5500000
categories sometimes required	The relevant IAB categories for this advertiser. See GET iab_categories. Note: Required when the line item’s placement is set to PUBLISHER_NETWORK. Type: string Example: IAB3-1
ios_app_store_identifier sometimes required	The numeric portion of the Apple App Store identifier for promoted applications. Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier. Type: string Example: 333903271
primary_web_event_tag sometimes required	The identifier of the primary web event tag. Allows more accurate tracking of engagements for the campaign pertaining to this line item. Note: Required when the line item’s goal is set to WEBSITE_CONVERSIONS. Type: string Example: nvo4z
advertiser_user_id optional	The X user identifier for the handle promoting a PREROLL_VIEWS ad. Only certain client applications may use this parameter. Type: string Example: 312226591
audience_expansion optional	Used to expand the reach of campaigns by targeting users similar to those already targeted. Note: By default, no expansion will be applied. Type: enum Possible values: BROAD, DEFINED, EXPANDED
bid_strategy optional	The bidding mechanism. AUTO automatically optimizes bidding based on daily budget and campaign flight dates. MAX sets the maximum allowable bid and is not available when the objective is set to REACH or FOLLOWERS. TARGET attempts to make daily bid averages within 20% of the specified bid_amount_local_micro and is available when the objective is set to REACH, FOLLOWERS, OR WEBSITE_CLICKS. Note: If set to AUTO, bid_amount_local_micro will be ignored. Note: Default based on objective. Type: enum Possible values: AUTO, MAX, TARGET
duration_in_days optional	The time period within which the frequency_cap is achieved. Type: int Possible values: 1, 7, 30
entity_status optional	The line item status. Type: enum Default: ACTIVE Possible values: ACTIVE, DRAFT, PAUSED
frequency_cap optional	The maximum number of times an ad could be delivered to a user. Note: Only supported for REACH, ENGAGEMENTS, VIDEO_VIEWS, and PREROLL_VIEWS objectives. Type: int Example: 5
goal optional	The optimization setting to use with this line item. The APP_PURCHASES option is available for APP_INSTALL. The APP_CLICKS and APP_INSTALLS options are available for both APP_INSTALL and APP_ENGAGEMENTS objectives and may require using a supported MACT partner. The SITE_VISITS option is only available with the WEBSITE_CLICKS objective. Note: Default based on objective. Type: enum Possible values: APP_CLICKS, APP_INSTALLS, APP_PURCHASES,ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, SITE_VISITS, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
name optional	The name for the line item. Type: string Example: demo Min, Max length: 1, 255
pay_by optional	The unit to charge this line item by. This setting can only be modified for line items using the APP_INSTALLS objective. Note: The default pay_by is automatically set based upon the campaign objective and line item’s bid unit. The APP_INSTALLS goal supports both APP_CLICK and IMPRESSION values. IMPRESSION is the default value. The LINK_CLICKS goal supports both LINK_CLICK and IMPRESSION values. IMPRESSION is the default value but is not supported when setting TARGET for bid_strategy. The SITE_VISITS goal supports IMPRESSION values. Type: enum Possible values: APP_CLICK, IMPRESSION, LINK_CLICK
standard_delivery optional	Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Only available when budget_optimization is set to LINE_ITEM for the parent campaign Type: boolean Default: true Possible values: true, false
total_budget_amount_local_micro optional	The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: 37500000
daily_budget_amount_local_micro sometimes required	The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Only available when budget_optimization is set to LINE_ITEM for the parent campaign Note: This should be less than or equal to the total_budget_amount_local_micro. Type: long Example: 5500000

Example Request

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

    {
      "request": {
        "params": {
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": "2022-06-15T00:00:00Z",
          "bid_amount_local_micro": 3210000,
          "daily_budget_amount_local_micro": 1000000,
          "product_type": "PROMOTED_TWEETS",
          "objective": "ENGAGEMENTS",
          "entity_status": "PAUSED",
          "account_id": "18ce54d4x5t",
          "campaign_id": "hwtq0"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": null,
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2022-06-15T00:00:00Z",
        "bid_amount_local_micro": 3210000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": 1000000,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": true,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "ml5vs",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2022-06-03T23:47:20Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-03T23:47:20Z",
        "campaign_id": "hwtq0",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

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-Type of application/json is 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.

Batch Responses

Batch API responses return an ordered collection of items. Otherwise, they are identical in structure to their corresponding single-item endpoints.

Batch Errors

• Request-level errors (eg. max batch size exceeded) are shown in the response under the errors object.
• Item-level errors (eg. missing required line item parameter) are shown in the response under the operation_errors object.

Resource URL

https://ads-api.x.com/12/batch/accounts/:account_id/line_items

Parameters

Name	Description
operation_type required	The per item operation type being performed. Type: enum Possible values: Create, Delete, Update
params required	A JSON object containing all the parameters for the line item objects. For a list of required and optional line item parameters, see here.

Example Request

POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/line_items

    [
      {
        "operation_type":"Create",
        "params":{
          "campaign_id":"8yn7m",
          "objective":"ENGAGEMENTS",
          "product_type":"PROMOTED_TWEETS",
          "placements":"ALL_ON_TWITTER",
          "bid_amount_local_micro":3210000,
          "entity_status":"PAUSED"
        }
      }
    ]

Example Response

    {
      "data": [
        {
          "advertiser_user_id": "756201191646691328",
          "name": null,
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": null,
          "bid_amount_local_micro": 3210000,
          "advertiser_domain": null,
          "target_cpa_local_micro": null,
          "primary_web_event_tag": null,
          "goal": "ENGAGEMENT",
          "daily_budget_amount_local_micro": null,
          "product_type": "PROMOTED_TWEETS",
          "end_time": null,
          "funding_instrument_id": "lygyi",
          "bid_strategy": "MAX",
          "duration_in_days": null,
          "standard_delivery": null,
          "total_budget_amount_local_micro": null,
          "objective": "ENGAGEMENTS",
          "id": "9cqi0",
          "entity_status": "PAUSED",
          "automatic_tweet_promotion": null,
          "frequency_cap": null,
          "android_app_store_identifier": null,
          "categories": [],
          "currency": "USD",
          "pay_by": "ENGAGEMENT",
          "created_at": "2017-07-07T17:42:20Z",
          "ios_app_store_identifier": null,
          "updated_at": "2017-07-07T17:42:20Z",
          "campaign_id": "8yn7m",
          "creative_source": "MANUAL",
          "deleted": false
        }
      ],
      "request": [
        {
          "params": {
            "placements": [
              "ALL_ON_TWITTER"
            ],
            "bid_amount_local_micro": 3210000,
            "product_type": "PROMOTED_TWEETS",
            "objective": "ENGAGEMENTS",
            "entity_status": "PAUSED",
            "account_id": "18ce54d4x5t",
            "campaign_id": "8yn7m"
          },
          "operation_type": "Create"
        }
      ]
    }

PUT accounts/:account_id/line_items/:line_item_id

Update the specified line item associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_id required	A reference to the line item you are operating with in the request. Type: string Example: 8v7jo
advertiser_domain optional	The website domain for this advertiser, without the protocol specification. Note: Required when the line item’s placement is set to PUBLISHER_NETWORK. Type: string Example: x.com
advertiser_user_id optional	The Twitter user identifier for the handle promoting a PREROLL_VIEWS ad. Only certain client applications may use this parameter. Type: string Example: 312226591
android_app_store_identifier optional	The Google App Store identifier for the promoted application. Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier. Type: string Example: com.twitter.android
audience_expansion optional	Used to expand the reach of campaigns by targeting users similar to those already targeted. Type: enum Possible values: BROAD, DEFINED, EXPANDED
bid_amount_local_micro optional	The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. Note: Required if bid_strategy is set to either MAX or TARGET Note: Only values greater than zero are accepted. Type: long Example: 140000
bid_strategy optional	The bidding mechanism. AUTO automatically optimizes bidding based on daily budget and campaign flight dates. MAX sets the maximum allowable bid and is not available when the objective is set to REACH or FOLLOWERS. TARGET attempts to make daily bid averages within 20% of the specified bid_amount_local_micro and is available when the objective is set to REACH or WEBSITE_CLICKS. Note: If set to AUTO, bid_amount_local_micro will be ignored. Note: Default based on objective. Type: enum Possible values: AUTO, MAX, TARGET
categories optional	The relevant IAB categories for this advertiser. See GET iab_categories. Note: Required when the line item’s placement is set to PUBLISHER_NETWORK. Type: string Example: IAB3-1
duration_in_days optional	The time period within which the frequency_cap is achieved. Type: int Possible values: 1, 7, 30
entity_status optional	The line item status. Type: enum Possible values: ACTIVE, PAUSED
end_time optional	The time, expressed in ISO 8601, that the line item will stop serving. Type: string Example: 2017-10-05T00:00:00Z
frequency_cap optional	The maximum number of times an ad could be delivered to a user. Note: Only supported for REACH, ENGAGEMENTS, VIDEO_VIEWS, and PREROLL_VIEWS objectives. Type: int Example: 5
goal optional	The optimization setting to use with this line item. The APP_PURCHASES option is available for APP_INSTALL. The APP_CLICKS and APP_INSTALLS options are available for APP_INSTALL and APP_ENGAGEMENTS and may require using a supported MACT partner. Note: Default based on objective. Type: enum Possible values: APP_CLICKS, APP_INSTALLS, APP_PURCHASES, ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
ios_app_store_identifier optional	The numeric portion of the Apple App Store identifier for promoted applications. Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier. Type: string Example: 333903271
name optional	The name for the line item. Type: string Example: demo
pay_by optional	The unit to charge this line item by. This setting can only be modified for line items using the APP_INSTALLS objective. Note: The default pay_by is automatically set based upon the campaign objective and line item’s bid unit. The APP_INSTALLS goal supports both APP_CLICK and IMPRESSION values. IMPRESSION is the default value. The LINK_CLICKS goal supports both LINK_CLICK and IMPRESSION values. IMPRESSION is the default value but is not supported when setting TARGET for bid_strategy. The SITE_VISITS goal supports IMPRESSION values. Type: enum Possible values: APP_CLICK, IMPRESSION, LINK_CLICK
start_time optional	The time, expressed in ISO 8601, that the line item will begin serving. Type: string Example: 2017-07-05T00:00:00Z
total_budget_amount_local_micro optional	The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: 37500000
daily_budget_amount_local_micro optional	The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Only available when budget_optimization is set to LINE_ITEM for the parent campaign Note: This should be less than or equal to the total_budget_amount_local_micro. Type: long Example: 5500000

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9cqi0?bid_amount_local_micro=140000

Example Response

    {
      "request": {
        "params": {
          "line_item_id": "9cqi0",
          "bid_amount_local_micro": 140000,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": null,
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2017-07-10T00:00:00Z",
        "bid_amount_local_micro": 140000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": null,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": null,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "9cqi0",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2017-07-07T17:42:20Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-03T23:51:36Z",
        "campaign_id": "8yn7m",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

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 if with_deleted=true is specified in the request. These promoted_tweets are not actually deleted, though ("deleted": false in the response). We do not cascade deletes.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_id required	A reference to the line item you are operating with in the request. Type: string Exampple: 9f2ix

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9f2ix

Example Response

    {
      "data": {
        "bid_strategy": "MAX",
        "advertiser_user_id": "756201191646691328",
        "name": "Untitled",
        "placements": [],
        "start_time": null,
        "bid_amount_local_micro": 100000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "pay_by": "ENGAGEMENT",
        "product_type": "PROMOTED_TWEETS",
        "end_time": "2017-07-21T00:00:00Z",
        "duration_in_days": 1,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "9f2ix",
        "entity_status": "ACTIVE",
        "goal": "ENGAGEMENT",
        "frequency_cap": 5,
        "categories": [],
        "currency": "USD",
        "created_at": "2017-07-14T00:01:50Z",
        "updated_at": "2017-08-09T07:41:08Z",
        "campaign_id": "90r8n",
        "creative_source": "MANUAL",
        "deleted": true
      },
      "request": {
        "params": {
          "line_item_id": "9f2ix",
          "account_id": "18ce54d4x5t"
        }
      }
    }

Line Item Curated Categories

Additional details on usage can be found at the Video Views Pre-roll Objective Guide

GET accounts/:account_id/line_item_curated_categories

Retrieve details for some or all line item curated categories associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories

Example Response

    {
      "request": {
        "params": {
          "account_id": "abc1"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "by5pw",
          "curated_category_id": "7op29tp2jzeo",
          "id": "1",
          "created_at": "2018-06-29T04:19:53Z",
          "updated_at": "2018-06-29T04:19:53Z",
          "deleted": false
        }
      ]
    }

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 URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_curated_category_id required	A reference to the line item curated category you are operating with in the request. Type: string Example: 43853bhii885
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories/yav

Example Response

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "yav",
          "account_id": "abc1"
        }
      },
      "data": {
        "line_item_id": "by5pw",
        "curated_category_id": "7op29tp2jzeo",
        "id": "yav",
        "created_at": "2018-06-29T04:19:53Z",
        "updated_at": "2018-06-29T04:19:53Z",
        "deleted": false
      }
    }

POST accounts/:account_id/line_item_curated_categories

Associate a curated category object with the specified line item.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
curated_category_id required	A reference to the curated category entity you are operating with in the request. Type: string Example: 10miy
line_item_id required	A reference to the line item you are operating with in the request. Type: string Example: 8v7jo

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories?line_item_id=iqwka&curated_category_id=9ddrgesiap6o

Example Response

    {
      "request": {
        "params": {
          "curated_category_id": "9ddrgesiap6o",
          "line_item_id": "iqwka",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "9ddrgesiap6o",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T17:26:42Z",
        "deleted": false
      }
    }

PUT accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Update the specified line item curated category.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_curated_category_id required	A reference to the line item curated category you are operating with in the request. Type: string Example: 1bzq3
curated_category_id optional	A reference to the curated category entity you are operating with in the request. Type: string Example: 10miy
line_item_id optional	A reference to the line item you are operating with in the request. Type: string Example: 8v7jo

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq?curated_category_id=8tujl1p3yn0g

Example Response

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "xq",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "8tujl1p3yn0g",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T18:22:52Z",
        "deleted": true
      }
    }

DELETE accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Delete the specified line item curated category.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_curated_category_id required	A reference to the line item curated category you are operating with in the request. Type: string Example: 1bzq3

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq

Example Response

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "xq",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "9ddrgesiap6o",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T18:22:52Z",
        "deleted": true
      }
    }

Line Item Placements

GET line_items/placements

Retrieve valid placement and product_type combinations.

Resource URL

https://ads-api.x.com/12/line_items/placements

Parameters

Name	Description
product_type optional	Scope the response to just the valid placements for the specified product type. Type: enum Possible values: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS

Example Request

GET https://ads-api.x.com/12/line_items/placements?product_type=PROMOTED_ACCOUNT

Example Response

    {
      "data": [
        {
          "product_type": "PROMOTED_ACCOUNT",
          "placements": [
            [
              "ALL_ON_TWITTER"
            ],
            [
              "TWITTER_TIMELINE"
            ]
          ]
        }
      ],
      "request": {
        "params": {
          "product_type": "PROMOTED_ACCOUNT"
        }
      }
    }

Media Creatives

GET accounts/:account_id/media_creatives

Retrieve details for some or all media creatives associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
campaign_id optional	Scope the response to just the media creatives associated with the specified campaign. Type: string Example: 8gdx6
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
line_item_ids optional	Scope the response to just the media creatives associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8v7jo
media_creative_ids optional	Scope the response to just the desired media creatives by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 1bzq3
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "media_creative_ids": [
            "1bzq3"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8v7jo",
          "landing_url": "https://dev.x.com",
          "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
          "id": "1bzq3",
          "entity_status": "ACTIVE",
          "created_at": "2017-07-05T06:00:42Z",
          "account_media_id": "10miy",
          "updated_at": "2019-01-11T20:21:26Z",
          "approval_status": "ACCEPTED",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/media_creatives/:media_creative_id

Retrieves details for a specific media creative associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
media_creative_id required	A reference to the media creative you are operating with in the request. Type: string Example: 43853bhii885
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3

Example Response

    {
      "request": {
        "params": {
          "media_creative_id": "1bzq3",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2019-01-11T20:21:26Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

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 media creative_type is PREROLL) or image ads (such as BANNER or INTERSTITIAL) on the Twitter Audience Platform.

Note: In order to add media assets to the Account Media resource, use the POST accounts/:account_id/media_library endpoint.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
account_media_id required	A reference to the account media entity you are operating with in the request. Type: string Example: 10miy
line_item_id required	A reference to the line item you are operating with in the request. Type: string Example: 8v7jo
landing_url sometimes required	The URL of the website to direct a user to. This should only be used with TAP images (or “display creatives”). This value will be ignored if used with preroll assets. To associate a URL with a preroll asset, use the POST accounts/:account_id/preroll_call_to_actions endpoint. Note: Required when the line item’s objective is set to WEBSITE_CLICKS. Type: string Example: https://blog.x.com/

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy

Example Response

    {
      "request": {
        "params": {
          "line_item_id": "8v7jo",
          "account_media_id": "10miy",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2019-01-11T20:21:26Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

DELETE accounts/:account_id/media_creatives/:media_creative_id

Delete the specified media creative belonging to the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
media_creative_id required	A reference to the media creative you are operating with in the request. Type: string Example: 1bzq3

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3

Example Response

    {
      "request": {
        "params": {
          "media_creative_id": "1bzq3",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2021-04-16T21:02:55Z",
        "approval_status": "ACCEPTED",
        "deleted": true
      }
    }

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 by user_id in the response.

An HTTP 400 will be returned if none of the specified line items are configured to contain promoted accounts.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
line_item_ids optional	Scope the response to just the promoted accounts associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 9bpb2
promoted_account_ids optional	Scope the response to just the desired promoted accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 19pl2
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2

Example Response

    {
      "request": {
        "params": {
          "promoted_account_ids": [
            "19pl2"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "9bpb2",
          "user_id": "756201191646691328",
          "id": "19pl2",
          "entity_status": "ACTIVE",
          "created_at": "2017-07-05T05:54:13Z",
          "updated_at": "2017-07-05T05:54:13Z",
          "approval_status": "ACCEPTED",
          "deleted": false
        }
      ]
    }

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 URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
promoted_account_id required	A reference to the promoted account you are operating with in the request. Type: string Example: 19pl2
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2

Example Response

    {
      "request": {
        "params": {
          "promoted_account_id": "19pl2",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-07-05T05:54:13Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

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, a HTTP 400 INCOMPATIBLE_LINE_ITEM error will be returned. If the specified user is ineligible for promotion, a HTTP 400 will be returned and no users will be promoted. If the provided user is already promoted, the request will be ignored.

For more information on Promoted Accounts, see our campaign management page.

Note: It is not possible to update (PUT) promoted accounts entities.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_id required	A reference to the line item you are operating with in the request. Type: string Example: 9bpb2
user_id required	A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name. Type: long Example: 756201191646691328

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328

Example Response

    {
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-07-05T05:54:13Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      },
      "request": {
        "params": {
          "user_id": "756201191646691328",
          "line_item_id": "9bpb2",
          "account_id": "18ce54d4x5t"
        }
      }
    }

DELETE accounts/:account_id/promoted_accounts/:promoted_account_id

Disassociate an account from the specified line item.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
promoted_account_id required	The identifier refers to the instance of a Promoted Account associated with a line item. Type: string Example: 19pl2

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2

Example Response

    {
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-08-23T18:53:15Z",
        "approval_status": "ACCEPTED",
        "deleted": true
      },
      "request": {
        "params": {
          "promoted_account_id": "19pl2",
          "account_id": "18ce54d4x5t"
        }
      }
    }

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 the tweet_id values for each promoted_tweets object.

Note: When parent line items are deleted, promoted_tweets are only returned if with_deleted=true is specified in the request. These promoted_tweets are not actually deleted, though ("deleted": false in the response).

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_tweets

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
line_item_ids optional	Scope the response to just the Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 96uzp
promoted_tweet_ids optional	Scope the response to just the desired promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 1efwlo
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo

Example Response

    {
      "request": {
        "params": {
          "promoted_tweet_ids": [
            "1efwlo"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "96uzp",
          "id": "1efwlo",
          "entity_status": "ACTIVE",
          "created_at": "2017-06-29T05:06:57Z",
          "updated_at": "2017-06-29T05:08:46Z",
          "approval_status": "ACCEPTED",
          "tweet_id": "880290790664060928",
          "deleted": false
        }
      ]
    }

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 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/:promoted_tweet_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
promoted_tweet_id required	A reference to the promoted Tweet you are operating with in the request. Type: string Example: 1efwlo
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1efwlo

Example Response

    {
      "request": {
        "params": {
          "promoted_tweet_id": "1efwlo",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "96uzp",
        "id": "1efwlo",
        "entity_status": "ACTIVE",
        "created_at": "2017-06-29T05:06:57Z",
        "updated_at": "2017-06-29T05:08:46Z",
        "approval_status": "ACCEPTED",
        "tweet_id": "880290790664060928",
        "deleted": false
      }
    }

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 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.

Note: It is not possible to update (PUT) promoted Tweet entities.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_tweets

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_id required	A reference to the line item you are operating with in the request. Type: string Example: 8v7jo
tweet_ids required	A comma-separated list of identifiers corresponding to specific Tweets. Up to 50 IDs may be provided. Type: long Example: 822333526255120384

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384

Example Response

    {
      "data": [
        {
          "line_item_id": "8v7jo",
          "id": "1e8i2k",
          "entity_status": "ACTIVE",
          "created_at": "2017-06-24T04:21:36Z",
          "updated_at": "2017-06-24T04:21:36Z",
          "approval_status": "ACCEPTED",
          "tweet_id": "822333526255120384",
          "deleted": false
        }
      ],
      "request": {
        "params": {
          "line_item_id": "8v7jo",
          "tweet_ids": [
            822333526255120384
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "total_count": 1
    }

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 URL

https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
promoted_tweet_id required	The identifier refers to the instance of a Promoted Tweet associated with a line item. This comes from the id field from a response item to GET accounts/:account_id/promoted_tweets, not the tweet_id of the Tweet in question. Supplied within the resource’s path. Type: string Example: 1gp8a5

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1gp8a5

Example Response

    {
      "data": {
        "line_item_id": "9pl99",
        "id": "1gp8a5",
        "entity_status": "ACTIVE",
        "created_at": "2017-08-17T17:02:21Z",
        "updated_at": "2017-08-18T06:43:48Z",
        "approval_status": "ACCEPTED",
        "tweet_id": "844796297743757315",
        "deleted": true
      },
      "request": {
        "params": {
          "promoted_tweet_id": "1gp8a5",
          "account_id": "18ce54d4x5t"
        }
      }
    }

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 either FULL or RETWEETS_ONLY. This controls the type of content that is allowed to be promoted by the account. Advertisers must obtain permission to promote another user’s content and contact Twitter to get them added to your account as a RETWEETS_ONLY promotable user.

Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you’d like to promote. You can use the POST accounts/:account_id/promoted-tweets endpoint to promote published Tweets and the POST accounts/:account_id/scheduled-promoted-tweets endpoint to promote another Twitter Ads account’s Scheduled Tweets.

You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the tweet_id that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The tweet_id that is returned corresponds to this new Tweet.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promotable_users

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
promotable_user_ids optional	Scope the response to just the desired promotable users by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: l310s
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s

Example Response

    {
      "request": {
        "params": {
          "promotable_user_ids": [
            "l310s"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "user_id": "756201191646691328",
          "id": "l310s",
          "created_at": "2016-07-21T22:42:09Z",
          "updated_at": "2016-07-21T22:42:09Z",
          "deleted": false,
          "promotable_user_type": "FULL"
        }
      ]
    }

GET accounts/:account_id/promotable_users/:promotable_user_id

Retrieve a specific promotable user associated with the current account.

The promotable user type is either FULL or RETWEETS_ONLY. This controls the type of content that is allowed to be promoted by the account.

Advertisers must obtain permission to promote another user’s content. Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you’d like to promote.

You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the tweet_id that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The tweet_id that is returned corresponds to this new Tweet.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promotable_users/:promotable_user_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
promotable_user_id optional	A reference to the promotable user you are operating on within the request Type: string Example: l310s
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users/l310s

Example Response

    {
      "request": {
        "params": {
          "promotable_user_id": "l310s",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "user_id": "2417045708",
        "id": "l310s",
        "created_at": "2017-03-10T17:51:24Z",
        "updated_at": "2017-03-10T17:51:24Z",
        "deleted": false,
        "promotable_user_type": "RETWEETS_ONLY"
      }
    }

Publishers

GET publishers

Retrieve a list of Content Category publishers’ details

Additional details can be found in the Video Views Preroll Objective Guide

Resource URL

https://ads-api.x.com/12/publishers

Parameters

No request parameters

Example Request

GET https://ads-api.x.com/12/publishers

Example Response

    {
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "PeoplesSports",
          "user_id": "1353868435021721602",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "JP"
          ],
          "username": "NewYork_Jack",
          "user_id": "1331177123436851206",
          "monetization_restricted": true,
          "content_category_ids": [
            "sk"
          ]
        },
        {
          "monetizable_country_codes": [
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "JP"
          ],
          "username": "twispatv",
          "user_id": "1331165719128461314",
          "monetization_restricted": true,
          "content_category_ids": [
            "sm"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "LAThieves",
          "user_id": "1316808678897455105",
          "monetization_restricted": true,
          "content_category_ids": [
            "s0"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "Quicktake_EE",
          "user_id": "1305900477427724290",
          "monetization_restricted": true,
          "content_category_ids": [
            "sr"
          ]
        },
        {
          "monetizable_country_codes": [
            "BR"
          ],
          "promotion_eligible_country_codes": [
            "BR"
          ],
          "username": "eufloribella",
          "user_id": "1300812459054436354",
          "monetization_restricted": true,
          "content_category_ids": [
            "sm"
          ]
        },
        {
          "monetizable_country_codes": [
            "EG"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "Egypt2021EN",
          "user_id": "1296077573399678977",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "ClubShayShay",
          "user_id": "1283068366706454529",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "hiaahsanshow",
          "user_id": "1253421442143641601",
          "monetization_restricted": false,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "TH"
          ],
          "promotion_eligible_country_codes": [
            "TH"
          ],
          "username": "HoneKrasae",
          "user_id": "1240684293719904256",
          "monetization_restricted": true,
          "content_category_ids": [
            "sr"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "Sportskind",
          "user_id": "1232708694418300930",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "almeerathShow",
          "user_id": "1229410512762437633",
          "monetization_restricted": false,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "SeeYourVoiceFOX",
          "user_id": "1225490734653947904",
          "monetization_restricted": true,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "AUProSports",
          "user_id": "1219303449768185859",
          "monetization_restricted": false,
          "content_category_ids": [
            "se"
          ]
        }
      ]
    }

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 URL

https://ads-api.x.com/5/accounts/:account_id/recommendations

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t

Example Request

GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations

Example Response

    "request": {
      "params": {
        "account_id": "18ce54d4x5t"
      }
    },
    "total_count": 1,
    "data": [
      {
        "funding_instrument_id": "gpvzb",
        "id": "62ce8zza1q0w",
        "account_id": "18ce54d4x5t",
        "status": "PENDING",
        "message": "Recommendation for testing",
        "created_at": "2016-11-14T23:07:54Z",
        "updated_at": "2016-11-14T23:07:54Z"
      }
    ]

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 URL

https://ads-api.x.com/5/accounts/:account_id/recommendations/:recommendation_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
recommendation_id required	A reference to the recommendation ID you are operating within the request Type: string Example: 62ce8zza1q0w

Example Request

GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations/62ce8zza1q0w

Example Response

    {
    "request": {
      "params": {
        "recommendation_id": "62ce8zza1q0w",
        "account_id": "18ce54d4x5t"
      }
    },
    "data_type": "recommendations",
      "data": {
      "changes": [
        {
          "entity_type": "campaigns",
          "params": {
            "start_time": "2016-11-08T22:00:00Z",
            "daily_budget_amount_local_micro": 2200000,
            "end_time": "2016-11-16T07:59:00Z",
            "total_budget_amount_local_micro": 12000000,
            "id": "64m0d"
          },
          "operation_type": "Update",
          "dependent_entities": [
            {
              "entity_type": "line_items",
              "params": {
                "name": "Campaign for recommendations",
                "placements": [
                  "TWITTER_TIMELINE"
                ],
                "bid_amount_local_micro": 1430000,
                "id": "6f5kq",
                "include_sentiment": "ALL"
              },
              "operation_type": "Update",
              "dependent_entities": [
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6p"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "election results",
                    "targeting_value": "election results",
                    "targeting_type": "PHRASE_KEYWORD"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101ftp"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "Male",
                    "targeting_value": 1,
                    "targeting_type": "GENDER"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "San Francisco-Oakland-San Jose CA, US",
                    "targeting_value": "",
                    "targeting_type": "LOCATION"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101fto"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "91125952589766656"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "Partner audience targeting",
                    "targeting_value": "v2cx",
                    "targeting_type": "NEGATIVE_BEHAVIOR"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "AGE_21_TO_34",
                    "targeting_value": "AGE_21_TO_34",
                    "targeting_type": "AGE"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6o"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991101965843460096"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991127212156096516"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "debate",
                    "targeting_value": "debate",
                    "targeting_type": "NEGATIVE_PHRASE_KEYWORD"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "60004, IL, US",
                    "targeting_value": "",
                    "targeting_type": "LOCATION"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6n"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101ftn"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                }
              ]
            }
          ]
        }
      ],
      "funding_instrument_id": "gpvzb",
      "id": "62ce8zza1q0w",
      "account_id": "18ce54d4x5t",
      "status": "PENDING",
      "message": "Recommendation for testing",
      "created_at": "2016-11-14T23:07:54Z",
      "updated_at": "2016-11-14T23:07:54Z"
      }
    }

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 URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
line_item_ids optional	Scope the response to just the scheduled Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8xdpe
scheduled_promoted_tweet_ids optional	Scope the response to just the desired scheduled promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 1xboq
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?scheduled_promoted_tweet_ids=1xboq

Example Response

    {
      "request": {
        "params": {
          "scheduled_promoted_tweet_ids": [
            "1xboq"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8xdpe",
          "id": "1xboq",
          "created_at": "2017-06-01T19:53:32Z",
          "updated_at": "2017-06-01T20:00:06Z",
          "scheduled_tweet_id": "870366669373194240",
          "tweet_id": "870369382207070208",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id

Retrieve a specific scheduled promoted Tweet associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
scheduled_promoted_tweet_id required	A reference to the scheduled promoted Tweet you are operating with in the request. Type: string Example: 1xboq
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xboq

Example Response

    {
      "request": {
        "params": {
          "scheduled_promoted_tweet_id": "1xboq",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8xdpe",
        "id": "1xboq",
        "created_at": "2017-06-01T19:53:32Z",
        "updated_at": "2017-06-01T20:00:06Z",
        "scheduled_tweet_id": "870366669373194240",
        "tweet_id": "870369382207070208",
        "deleted": false
      }
    }

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 URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_id required	A reference to the line item you are operating with in the request. Type: string Example: 8xdpe
scheduled_tweet_id required	A reference to the scheduled Tweet you are operating with in the request. Type: long Example: 870358555227860992

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?line_item_id=8xdpe&scheduled_tweet_id=870358555227860992

Example Response

    {
      "data": {
        "line_item_id": "8xdpe",
        "id": "1xtfl",
        "created_at": "2017-06-08T07:25:26Z",
        "updated_at": "2017-06-08T07:25:26Z",
        "scheduled_tweet_id": "870358555227860992",
        "tweet_id": null,
        "deleted": false
      },
      "request": {
        "params": {
          "line_item_id": "8xdpe",
          "scheduled_tweet_id": 870358555227860992,
          "account_id": "18ce54d4x5t"
        }
      }
    }

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_tweets/:scheduled_tweet_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
scheduled_promoted_tweet_id required	A reference to the scheduled promoted Tweet you are operating with in the request. This is the id attribute from a GET accounts/:account_id/scheduled_promoted_tweets response object. Type: string Example: 1xtfl

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xtfl

Example Response

    {
      "data": {
        "line_item_id": "8xdpe",
        "id": "1xtfl",
        "created_at": "2017-06-08T07:25:26Z",
        "updated_at": "2017-06-15T05:14:12Z",
        "scheduled_tweet_id": "870358555227860992",
        "tweet_id": null,
        "deleted": true
      },
      "request": {
        "params": {
          "scheduled_promoted_tweet_id": "1xtfl",
          "account_id": "18ce54d4x5t"
        }
      }
    }

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.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/targeting_criteria

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_ids required	Scope the response to just the targeting criteria under the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8u94t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
lang optional	An ISO-639-1 language code. When passed, an additional localized_name attribute will be returned in the response for objects where a localized name is available. Type: string Example: fr
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
targeting_criterion_ids optional	Scope the response to just the desired targeting criteria by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: dpl3a6
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_ids=8u94t

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "line_item_ids": [
            "8u94t"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8u94t",
          "name": "Custom audience targeting",
          "id": "dpl3a6",
          "operator_type": "EQ",
          "created_at": "2017-05-26T03:29:35Z",
          "targeting_value": "249yj",
          "updated_at": "2017-05-26T03:29:35Z",
          "deleted": false,
          "targeting_type": "CUSTOM_AUDIENCE"
        }
      ]
    }

GET accounts/:account_id/targeting_criteria/:targeting_criterion_id

Retrieve a specific targeting criterion associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
targeting_criterion_id required	A reference to the targeting criterion you are operating with in the request. Type: string Example: eijd4y
lang optional	An ISO-639-1 language code. When passed, an additional localized_name attribute will be returned in the response for objects where a localized name is available. Type: string Example: fr
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/eijd4y

Example Response

    {
      "request": {
        "params": {
          "targeting_criterion_id": "eijd4y",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "619jl",
        "name": "🤖",
        "id": "eijd4y",
        "created_at": "2017-07-06T16:51:04Z",
        "targeting_value": "🤖",
        "updated_at": "2017-07-06T16:51:04Z",
        "deleted": false,
        "targeting_type": "BROAD_KEYWORD"
      }
    }

POST accounts/:account_id/targeting_criteria

See the Targeting Options page to find targeting_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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_id required	A reference to the line item you are operating with in the request. Type: string Example: 69ob
operator_type required	Specify the relationship that the targeting criterion should have. For example, to exclude keywords, use operator_type=NE. Type: enum Possible values: EQ, NE, GTE, LT
targeting_type required	The type of targeting that will be applied to this line item. Possible non-keyword-based values include: AGE, DEVICE, EVENT, CAMPAIGN_ENGAGEMENT, CAMPAIGN_ENGAGEMENT_LOOKALIKE, CONVERSATION, ENGAGEMENT_TYPE, FOLLOWERS_OF_USER, GENDER, INTEREST, LANGUAGE, LIVE_TV_EVENT, LOCATION, NETWORK_ACTIVATION_DURATION, NETWORK_OPERATOR, PLATFORM, PLATFORM_VERSION, SIMILAR_TO_FOLLOWERS_OF_USER, TV_SHOW, USER_ENGAGEMENT, USER_ENGAGEMENT_LOOKALIKE, WIFI_ONLY Note: It is only possible to target a single AGE bucket per line item. Possible keyword-based values include: BROAD_KEYWORD, EXACT_KEYWORD, PHRASE_KEYWORD, UNORDERED_KEYWORD Possible custom audience values include: CUSTOM_AUDIENCE, CUSTOM_AUDIENCE_EXPANDED Possible installed app store category values: APP_STORE_CATEGORY, APP_STORE_CATEGORY_LOOKALIKE Possible Twitter Audience Platform (TAP) app exclusion: APP_LIST (may only be used with operator_type=NE)
targeting_value required	Specify which user, which interest, which location, which event, which platform, which platform version, which device, which keyword or phrase, which gender, which custom audience, which app store category, or which exclusion of an app list this targeting will be applied to, depending on the selected targeting_type. Type: string Example: 174958347

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology

Example Response

    {
      "data": {
        "line_item_id": "619jl",
        "name": "technology",
        "id": "fbyjlr",
        "created_at": "2017-09-06T07:31:21Z",
        "targeting_value": "technology",
        "updated_at": "2017-09-06T07:31:21Z",
        "deleted": false,
        "targeting_type": "BROAD_KEYWORD"
      },
      "request": {
        "params": {
          "line_item_id": "619jl",
          "targeting_type": "BROAD_KEYWORD",
          "targeting_value": "technology",
          "account_id": "18ce54d4x5t"
        }
      }
    }

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-Type of application/json is 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.

Batch Responses

Batch API responses return an ordered collection of items. Otherwise, they are identical in structure to their corresponding single-item endpoints.

Batch Errors

• Request-level errors (eg. max batch size exceeded) are shown in the response under the errors object.
• Item-level errors (eg. missing required Targeting Criteria parameter) are shown in the response under the operation_errors object.

Resource URL

https://ads-api.x.com/12/batch/accounts/:account_id/targeting_criteria

Parameters

Name	Description
operation_type required	The per item operation type being performed. Type: enum Possible values: Create, Delete
params required	A JSON object containing all the parameters for the targeting criteria objects. For a list of required and optional targeting criteria parameters, see here. In addition, this endpoint supports an operator_type parameter that works in conjunction with certain targeting_type values. The possible values for this parameter are EQ for equal to, GTE for greater than or equal to, LT for less than, and NE for not equal to.

Example Request

POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/targeting_criteria

    [
      {
        "operation_type":"Create",
        "params":{
          "line_item_id":"6f9an",
          "targeting_type":"LOCATION",
          "targeting_value":"5122804691e5fecc"
        }
      },
      {
        "operation_type":"Delete",
        "params":{
          "targeting_criterion_id":"al2rua"
        }
      }
    ]

Example Response

    {
      "data_type": "targeting_criterion",
      "data": [
        {
          "line_item_id": "6f9an",
          "name": "San Francisco-Oakland-San Jose CA, US",
          "id": "al7vt2",
          "location_type": "CITY",
          "operator_type": "EQ",
          "created_at": "2016-11-11T22:59:50Z",
          "targeting_value": "5122804691e5fecc",
          "updated_at": "2016-11-11T22:59:50Z",
          "deleted": false,
          "targeting_type": "LOCATION"
        },
        {
          "line_item_id": "6keuo",
          "name": "accounts",
          "id": "al2rua",
          "operator_type": "EQ",
          "created_at": "2016-11-11T17:50:19Z",
          "targeting_value": "accounts",
          "updated_at": "2016-11-11T22:59:50Z",
          "deleted": true,
          "targeting_type": "BROAD_KEYWORD"
        }
      ],
      "request": [
        {
          "params": {
            "line_item_id": "6f9an",
            "targeting_type": "LOCATION",
            "targeting_value": "5122804691e5fecc",
            "account_id": "18ce54d4x5t"
          },
          "operation_type": "Create"
        },
        {
          "params": {
            "targeting_criterion_id": "al2rua",
            "account_id": "18ce54d4x5t"
          },
          "operation_type": "Delete"
        }
      ]
    }

DELETE accounts/:account_id/targeting_criteria/:targeting_criterion_id

Delete the specified targeting criterion belonging to the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
targeting_criterion_id required	A reference to the targeting criterion you are operating with in the request. Type: string Example: dpl3a6

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/dpl3a6

Example Response

    {
      "data": {
        "line_item_id": "8u94t",
        "name": "Custom audience targeting",
        "id": "dpl3a6",
        "created_at": "2017-05-26T03:29:35Z",
        "targeting_value": "249yj",
        "updated_at": "2017-08-30T18:38:58Z",
        "deleted": true,
        "targeting_type": "CUSTOM_AUDIENCE"
      },
      "request": {
        "params": {
          "targeting_criterion_id": "dpl3a6",
          "account_id": "18ce54d4x5t"
        }
      }
    }

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 URL

https://ads-api.x.com/12/targeting_criteria/app_store_categories

Parameters

Name	Description
q optional	An optional query to scope a targeting criteria. Omit this parameter to retrieve all. Type: string Example: music
os_type optional	Scope the results by a specific app store. Type: enum Possible values: ANDROID, IOS

Example Request

GET https://ads-api.x.com/12/targeting_criteria/app_store_categories?q=music&os_type=IOS

Example Response

    {
      "data": [
        {
          "name": "Games: Music",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qouq",
          "os_type": "IOS"
        },
        {
          "name": "Music",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qov2",
          "os_type": "IOS"
        }
      ],
      "request": {
        "params": {
          "q": "music",
          "os_type": "IOS"
        }
      }
    }

GET targeting_criteria/conversations

Discover available conversation-based targeting criteria for Promoted Products.

Resource URL

https://ads-api.x.com/12/targeting_criteria/conversations

Parameters

Name	Description
conversation_type optional	An optional query to scope to a certain conversation type. Type: enum Possible values: ACTORS, ATHLETES, BOOK_GENRES, BOOKS, BRAND_CATEGORIES, BRANDS, CELEBRITIES, COACHES, DIGITAL_CREATORS, ENTERTAINMENT_BRANDS, ENTERTAINMENT_PERSONALITIES, FICTIONAL_CHARACTERS, JOURNALISTS, LIFESTYLES, MOVIE_GENRES, MOVIES, MUSIC_GENRES, MUSICIANS, NEWS_STORIES, NEWS, PERSONS, PLACES, PODCASTS, POLITICAL_AFFILIATIONS, POLITICIANS, PRODUCTS, RADIO_STATIONS, SPORTS_LEAGUES, SPORTS_PERSONALITIES, SPORTS_TEAMS, SPORTS, TRENDS, TV_SHOWS, VIDEO_GAME_PLATFORMS, VIDEO_GAME_PUBLISHERS, VIDEO_GAMES
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow

Example Request

GET https://ads-api.x.com/12/targeting_criteria/conversations?count=2

Example Response

    {
      "request": {
        "params": {
          "count": 2
        }
      },
      "next_cursor": "1f7m7",
      "data": [
        {
          "targeting_type": "CONVERSATION",
          "targeting_value": "a1",
          "name": "NFL",
          "conversation_type": "SPORTS"
        },
        {
          "targeting_type": "CONVERSATION",
          "targeting_value": "a2",
          "name": "NBA",
          "conversation_type": "SPORTS"
        }
      ]
    }

GET targeting_criteria/devices

Discover available device-based targeting criteria for Promoted Products. Device targeting is available for Promoted Tweets.

Resource URL

https://ads-api.x.com/12/targeting_criteria/devices

Parameters

Name	Description
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
q optional	An optional query to scope a targeting criteria. Omit this parameter to retrieve all. Type: string Example: apple

Example Request

GET https://ads-api.x.com/12/targeting_criteria/devices?count=2&q=iphone

Example Response

    {
      "data": [
        {
          "name": "iPhone 3GS",
          "manufacturer": "Apple",
          "os_type": "iOS",
          "targeting_value": "1q",
          "targeting_type": "DEVICE"
        },
        {
          "name": "iPhone 4",
          "manufacturer": "Apple",
          "os_type": "iOS",
          "targeting_value": "1r",
          "targeting_type": "DEVICE"
        }
      ],
      "request": {
        "params": {
          "q": "iphone",
          "count": 2
        }
      }
    }

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 event start_time and end_time values on this endpoint are represented in UTC±00:00, irrespective of the event’s locale and timezone. This design should be kept in mind when querying and interacting with event start_time and end_time values. For example, Independence Day for the US is represented as start_time=2017-07-04T00:00:00Z and end_time=2017-07-05T00:00:00Z in UTC±00:00, and thus avoids the issue of this holiday existing across multiple timezones within the US.

Resource URL

https://ads-api.x.com/12/targeting_criteria/events

Parameters

Name	Description
event_types required	An optional query to scope to certain event types. Type: enum Possible values: CONFERENCE, HOLIDAY, MUSIC_AND_ENTERTAINMENT, OTHER, POLITICS, RECURRING, SPORTS
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
country_codes optional	An optional query to scope a targeting criteria search to particular countries with the 2 letter ISO country code. If this parameter is not specified, all events are returned. Type: string
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
end_time optional	The time, expressed in ISO 8601, that the campaign will end. Type: string Example: 2017-10-05T00:00:00Z
start_time optional	The time, expressed in ISO 8601, that the line item will begin serving. Note: Defaults to the current time. Type: string Example: 2017-07-05T00:00:00Z

Example Request

GET https://ads-api.x.com/12/targeting_criteria/events?count=1

Example Response

    {
      "request": {
        "params": {
          "count": 1
        }
      },
      "data_type": "events",
      "data": [
        {
          "reach": {
            "total_reach": null
          },
          "name": "New Year's",
          "start_time": "2017-12-31T00:00:00Z",
          "top_users": [],
          "top_tweets": [],
          "top_hashtags": [],
          "gender_breakdown_percentage": {},
          "end_time": "2018-01-02T00:00:00Z",
          "country_code": null,
          "device_breakdown_percentage": {},
          "targeting_value": "1ex",
          "is_global": true,
          "event_type": "HOLIDAY",
          "country_breakdown_percentage": {}
        }
      ],
      "next_cursor": "uww0"
    }

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 URL

https://ads-api.x.com/12/targeting_criteria/interests

Parameters

Name	Description
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
q optional	An optional query to scope a targeting criteria. Omit this parameter to retrieve all. Type: string Example: books

Example Request

GET https://ads-api.x.com/12/targeting_criteria/interests?q=books

Example Response

    {
      "data": [
        {
          "name": "Books and literature/Biographies and memoirs",
          "targeting_type": "INTEREST",
          "targeting_value": "1001"
        }
      ],
      "request": {
        "params": {
          "q": "books",
          "count": 1
        }
      },
      "next_cursor": "6by4n4"
    }

GET targeting_criteria/languages

Discover languages available for targeting.

Resource URL

https://ads-api.x.com/12/targeting_criteria/languages

Parameters

Name	Description
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
q optional	An optional query to scope a targeting criteria. Omit this parameter to retrieve all. Type: string Example: english

Example Request

GET https://ads-api.x.com/12/targeting_criteria/languages?q=english

Example Response

    {
      "data": [
        {
          "name": "English",
          "targeting_type": "LANGUAGE",
          "targeting_value": "en"
        }
      ],
      "request": {
        "params": {
          "q": "english"
        }
      },
      "next_cursor": null
    }

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 the CITIES enum with the location_type request parameter.

To target Designated Market Areas (DMAs), use the METROS enum.

Resource URL

https://ads-api.x.com/12/targeting_criteria/locations

Parameters

Name	Description
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
country_code optional	An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. Omit this parameter to retrieve results for all countries. Type: string Example: JP
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
location_type optional	Scope the results by a specific kind of location. More granular targeting than COUNTRIES may not be available in all locations. Type: enum Possible values: COUNTRIES, REGIONS, METROS, CITIES, POSTAL_CODES
q optional	An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results. Type: string Example: New York

Example Request

GET https://ads-api.x.com/12/targeting_criteria/locations?location_type=CITIES&q=los angeles

Example Response

    {
      "data": [
        {
          "name": "Los Angeles, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "3b77caf94bfc81fe",
          "targeting_type": "LOCATION"
        },
        {
          "name": "East Los Angeles, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "67571a7baaa5906b",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Lake Los Angeles, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "ea9bfbd43c93400f",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Gatos, San Francisco-Oakland-San Jose CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "a2de7c70b82b0ca0",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Altos, Monterey-Salinas CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "6a4364ea6f987c10",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Banos, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "b1b6fc646de75904",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Alamitos, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "0799ff0a3c1006e9",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Angeles, US",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "019940ae78c7b3bc",
          "targeting_type": "LOCATION"
        }
      ],
      "request": {
        "params": {
          "location_type": "CITIES",
          "q": "los angeles"
        }
      },
      "next_cursor": null
    }

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 URL

https://ads-api.x.com/12/targeting_criteria/network_operators

Parameters

Name	Description
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
country_code optional	An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. If this parameter is not specified only partner audiences for the United States are returned. Type: string Default: US
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
q optional	An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results. Type: string Examples: Airpeak

Example Request

GET https://ads-api.x.com/12/targeting_criteria/network_operators?count=5&country_code=US

Example Response

    {
      "data": [
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Advantage",
          "targeting_value": "2l"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Aeris",
          "targeting_value": "1b"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Airadigm",
          "targeting_value": "2t"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Airlink PCS",
          "targeting_value": "14"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Airpeak",
          "targeting_value": "1i"
        }
      ],
      "request": {
        "params": {
          "country_code": "US",
          "count": 5
        }
      },
      "next_cursor": "o7x9iet1a5u608olj4"
    }

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 URL

https://ads-api.x.com/12/targeting_criteria/platform_versions

Parameters

Name	Description
q optional	An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results. Type: string Examples: jelly bean

Example Request

GET https://ads-api.x.com/12/targeting_criteria/platform_versions

Example Response

    {
        "data": [
            {...},
            {
                "name": "Ice Cream Sandwich",
                "number": "4.0",
                "os_type": "Android",
                "targeting_type": "PLATFORM_VERSION",
                "targeting_value": "17"
            },
            {
                "name": "Jelly Bean",
                "number": "4.1",
                "os_type": "Android",
                "targeting_type": "PLATFORM_VERSION",
                "targeting_value": "18"
            },
            {...}
        ],
        "data_type": "targeting_criterion",
        "request": {
            "params": {}
        }
    }

GET targeting_criteria/platforms

Discover available platform-based targeting criteria for Promoted Products.

Resource URL

https://ads-api.x.com/12/targeting_criteria/platforms

Parameters

Name	Description
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
q optional	An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results. Type: string Examples: ios, blackberry
lang optional	Using a ISO-639-1 language code. When passed, an additional localized_name attribute will be returned in the response. Type: int, string Example: fr

Example Request

GET https://ads-api.x.com/12/targeting_criteria/platforms

Example Response

    {
      "data": [
        {
          "name": "iOS",
          "targeting_type": "PLATFORM",
          "targeting_value": "0"
        },
        {
          "name": "Android",
          "targeting_type": "PLATFORM",
          "targeting_value": "1"
        },
        {
          "name": "BlackBerry phones and tablets",
          "targeting_type": "PLATFORM",
          "targeting_value": "2"
        },
        {
          "name": "Mobile web on other devices",
          "targeting_type": "PLATFORM",
          "targeting_value": "3"
        },
        {
          "name": "Desktop and laptop computers",
          "targeting_type": "PLATFORM",
          "targeting_value": "4"
        }
      ],
      "request": {
        "params": {}
      }
    }

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 URL

https://ads-api.x.com/12/targeting_criteria/tv_markets

Parameters

None

Example Request

GET https://ads-api.x.com/12/targeting_criteria/tv_markets

Example Response

    {
      "data": [
        {
          "name": "France",
          "country_code": "FR",
          "locale": "fr-FR"
        },
        {
          "name": "Chile",
          "country_code": "CL",
          "locale": "es-CL"
        },
        {
          "name": "Germany",
          "country_code": "DE",
          "locale": "de-DE"
        },
        {
          "name": "Netherlands",
          "country_code": "NL",
          "locale": "nl-NL"
        },
        {
          "name": "United States",
          "country_code": "US",
          "locale": "en-US"
        },
        {
          "name": "Venezuela",
          "country_code": "VE",
          "locale": "es-VE"
        },
        {
          "name": "Brazil",
          "country_code": "BR",
          "locale": "pt-BR"
        },
        {
          "name": "Mexico",
          "country_code": "MX",
          "locale": "es-MX"
        },
        {
          "name": "Colombia",
          "country_code": "CO",
          "locale": "es-CO"
        },
        {
          "name": "United Kingdom",
          "country_code": "GB",
          "locale": "en-GB"
        },
        {
          "name": "Argentina",
          "country_code": "AR",
          "locale": "es-AR"
        },
        {
          "name": "Japan",
          "country_code": "JP",
          "locale": "ja-JP"
        },
        {
          "name": "Canada",
          "country_code": "CA",
          "locale": "en-CA"
        },
        {
          "name": "Spain",
          "country_code": "ES",
          "locale": "es-ES"
        },
        {
          "name": "Italy",
          "country_code": "IT",
          "locale": "it-IT"
        },
        {
          "name": "United States - Hispanic",
          "country_code": "US",
          "locale": "es-US"
        },
        {
          "name": "Ireland",
          "country_code": "IE",
          "locale": "en-IE"
        }
      ],
      "request": {
        "params": {}
      }
    }

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 an estimated_users value of 1000.

Note: TV channel and genre targeting options are no longer supported.

Resource URL

https://ads-api.x.com/12/targeting_criteria/tv_shows

Parameters

Name	Description
locale required	A required parameter that specifies the tv_market_locale to query for available TV shows. TV markets are queried based on locale returned from the GET targeting_criteria/tv_markets. Type: string Example: en-US
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 50 Min, Max: 1, 50
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
q optional	An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results. Type: string Examples: ios, blackberry

Example Request

GET https://ads-api.x.com/12/targeting_criteria/tv_shows?locale=en-US&q=news&count=1

Example Response

    {
      "data": [
        {
          "name": "NewsWatch",
          "targeting_value": 10027243420,
          "genre": "PAID",
          "locales": [
            {
              "language": "en",
              "country": "US"
            }
          ]
        }
      ],
      "next_cursor": "c-22838-zdQDJrTxSvOYfQOhb2IlGQ",
      "request": {
        "params": {
          "locale": {
            "countryCode": "US",
            "languageCode": "en"
          },
          "count": 1,
          "q": "news"
        }
      }
    }

Targeting Suggestions

GET accounts/:account_id/targeting_suggestions

Get up to 50 keyword or user targeting suggestions to complement your initial selection.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/targeting_suggestions

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticating user. Type: string Example: 18ce54d4x5t
suggestion_type required	Specify the type of suggestions to return. Type: enum Possible values: KEYWORD, USER_ID
targeting_values required	Comma separated collection of either keywords or user IDs used to seed the suggestions. Note: These two types of suggestions cannot be mixed. Example: 756201191646691328
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 30 Min, Max: 1, 50

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_suggestions?suggestion_type=KEYWORD&targeting_values=developers&count=2"

Example Response

    {
      "data": [
        {
          "suggestion_type": "KEYWORD",
          "suggestion_value": "devs"
        },
        {
          "suggestion_type": "KEYWORD",
          "suggestion_value": "software"
        }
      ],
      "request": {
        "params": {
          "suggestion_type": "KEYWORD",
          "targeting_values": [
            "developers"
          ],
          "count": 2,
          "account_id": "18ce54d4x5t"
        }
      }
    }

Tax Settings

GET accounts/:account_id/tax_settings

Retrieve tax setting details associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tax_settings

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "tax_id": "GB896391250",
        "address_city": "London",
        "business_relationship": "SELF",
        "address_street1": "21 March St",
        "address_last_name": null,
        "address_company": "ABC, Inc.",
        "tax_category": "BUSINESS_WITH_VAT",
        "address_postal_code": "SW1A 1AA",
        "bill_to": "NOT_SET",
        "address_region": "London",
        "address_country": "GB",
        "address_first_name": null,
        "invoice_jurisdiction": "NOT_SET",
        "address_street2": null,
        "address_email": null
      }
    }

PUT accounts/:account_id/tax_settings

Update the tax settings for the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tax_settings

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
address_city optional	The city for the account owner’s address. Type: string Example: San Francisco
address_country optional	The two-letter country code for the account owner’s address. Type: string Example: US
address_email optional	The email associated with the account owner’s address. Type: string Example: [e-mail]
address_first_name optional	The first name for the account owner’s address. Type: string Example: API
address_last_name optional	The last name for the account owner’s address. Type: string Example: McTestface
address_name optional	The company name for the account owner’s address. Type: string Example: ABC, Co.
address_postal_code optional	The postal code for the account owner’s address. Type: string Example: 94102
address_region optional	The region for the account owner’s address. Type: string Example: California
address_street1 optional	The street line for the account owner’s address. Type: string Example: 21 March St
address_street2 optional	The second street line for the account owner’s address. Type: string Example: Suite 99
bill_to optional	The entity that is billed. Type: enum Possible values: ADVERTISER, AGENCY
business_relationship optional	Whether the account is owned by the advertiser or by the agency. Type: enum Possible values: AGENCY, SELF
client_address_city optional	The city for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: Toronto
client_address_country optional	The two-letter country code for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: CA
client_address_email optional	The email associated with the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: [e-mail]
client_address_first_name optional	The first name for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: Brand
client_address_last_name optional	The last name for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: Advertiser
client_address_name optional	The company name for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: Brand, Inc.
client_address_postal_code optional	The postal code for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: M5H 2N2
client_address_region optional	The region for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: Ontario
client_address_street1 optional	The street line for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: 280 Queen St W
client_address_street2 optional	The second street line for the advertiser’s address. Set this when the ads account is owned by an agency. Type: string Example: The 6
invoice_jurisdiction optional	Invoice jurisdiction. Type: enum Possible values: LOI_SAPIN, NONE, NOT_SET
tax_category optional	Whether the taxation should be individual or business. Type: enum Possible values: BUSINESS_NO_VAT, BUSINESS_WITH_VAT, INDIVIDUAL
tax_exemption_id optional	VAT exemption ID. Type: sting Example: 12345
tax_id optional	VAT registration ID. Type: string Possible values: 67890

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings?address_name=ABC, Co.

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "address_name": "ABC Co."
        }
      },
      "data": {
        "tax_id": "GB896391250",
        "address_city": "London",
        "business_relationship": "SELF",
        "address_street1": "21 March St",
        "address_last_name": null,
        "address_company": "ABC, Co.",
        "tax_category": "BUSINESS_WITH_VAT",
        "address_postal_code": "SW1A 1AA",
        "bill_to": "NOT_SET",
        "address_region": "London",
        "address_country": "GB",
        "address_first_name": null,
        "invoice_jurisdiction": "NOT_SET",
        "address_street2": null,
        "address_email": null
      }
    }

Tracking Tags

GET accounts/:account_id/tracking_tags

Retrieve details for some or all tracking tags associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tracking_tags

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
line_item_ids optional	Scope the response to just the tracking tags associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 96uzp
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
tracking_tag_ids optional	Scope the response to just the desired tracking tags by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 3m82
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?tracking_tag_ids=3m82

Example Response

    {
      "request": {
        "params": {
          "tracking_tag_ids": [
            "3m82"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "fdwcl",
          "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
          "tracking_tag_type": "IMPRESSION_TAG",
          "id": "3m82",
          "created_at": "2019-06-26T17:04:26Z",
          "updated_at": "2019-06-26T17:04:26Z",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/tracking_tags/:tracking_tag_id

Retrieve a specific tracking tag associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
tracking_tag_id required	A reference to the tracking tag you are operating with in the request. Type: string Example: 555j
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j

Example Response

    {
      "request": {
        "params": {
          "with_deleted": true,
          "tracking_tag_id": "555j",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "72v2x",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N6344.2061500TWITTER-OFFICIAL/B23028778.279118262;dc_trk_aid=473354132;dc_trk_cid=119658253",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "555j",
        "created_at": "2020-08-13T23:02:03Z",
        "updated_at": "2020-08-13T23:02:03Z",
        "deleted": false
      }
    }

POST accounts/:account_id/tracking_tags

Associate a tracking tag with the specified line item.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tracking_tags

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_id required	A reference to the line item you are operating with in the request. Type: string Example: 8v7jo
tracking_tag_type required	The type of tracking tag. Type: enum Possible value: IMPRESSION_TAG, CLICK_TRACKER
tracking_tag_url required	The tracking tag url provided by the tracking partner. Type: string Example: https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Example Request

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

    {
      "request": {
        "params": {
          "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",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "fdwcl",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "3m82",
        "created_at": "2019-06-26T17:04:26Z",
        "updated_at": "2019-06-26T17:04:26Z",
        "deleted": false
      }
    }

PUT accounts/:account_id/tracking_tags/:tracking_tag_id

Associate a tracking tag with the specified line item.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
tracking_tag_url required	The tracking tag url provided by the tracking partner. Type: string Example: https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Example Request

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

    {
      "request": {
        "params": {
          "tracking_tag_id": "3m82",
          "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "fdwcl",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "3m82",
        "created_at": "2019-06-26T17:04:26Z",
        "updated_at": "2022-01-26T17:04:26Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/tracking_tags/:tracking_tag_id

Disassociate a tracking tag from the specified line item.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
tracking_tag_id required	A reference to the tracking tag you are operating with in the request. Type: string Example: 555j

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j

Example Response

    {
      "request": {
        "params": {
          "tracking_tag_id": "555j",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "72v2x",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N6344.2061500TWITTER-OFFICIAL/B23028778.279118262;dc_trk_aid=473354132;dc_trk_cid=119658253",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "555j",
        "created_at": "2020-08-13T23:02:03Z",
        "updated_at": "2021-08-29T17:12:58Z",
        "deleted": true
      }
    }

User Settings

(https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87)

GET accounts/:account_id/user_settings/:user_id

Retrieves user settings.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
user_id required	A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name. Type: long Example: 756201191646691328

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328

Example Response

      {
        "request": {
          "params": {
            "account_id": "18ce54d4x5t",
            "user_id": "756201191646691328"
          }
        },
        "data": {
          "notification_email": "[e-mail]",
          "contact_phone": "",
          "contact_phone_extension": ""
        }
      }

PUT accounts/:account_id/user_settings/:user_id

Updates user settings. Requires user context. Not accessible by account admins.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
user_id required	A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name. Type: long Example: 756201191646691328
notification_email optional	Email to use for account notifications. Type: string Example: [e-mail]
contact_phone optional	Contact phone number. Type: string Example: 202-555-0128
contact_phone_extension optional	Extension for contact contact_phone. Type: string Example: 1234

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328?notification_email='[e-mail]'&subscribe_email_types=ACCOUNT_PERFORMANCE,PERFORMANCE_IMPROVEMENT"

Example Response

      {
        "request": {
          "params": {
            "account_id": "18ce54d4x5t",
            "user_id": "756201191646691328"
            "notification_email": "[e-mail]",
            "subscribed_campaign_events": [
              "ACCOUNT_PERFORMANCE",
              "PERFORMANCE_IMPROVEMENT"
            ]
          }
        },
        "data": {
          "notification_email": "[e-mail]",
          "contact_phone": "",
          "Contact_phone_extension": ""
        }
      }