> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Campaign Management API Reference

> Endpoint reference for the X Ads Campaign Management API covering accounts, campaigns, line items, funding instruments, and targeting criteria requests.

## API Reference

<Note>
  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{" "}
  <a href="/x-ads-api/campaign-management">Campaign Management Overview</a>.
</Note>

### Accounts

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts[](#get-accounts "Permalink to this headline")

Retrieve details for some or all advertising-enabled accounts the authenticating user has access to.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField query="account_ids" type="string" optional>
  Scope the response to just the desired account IDs by specifying a comma-separated list of identifiers.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.
  <br />Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope resource by `name`. Performs case-insensitive prefix matching.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.
  <br /><br />**Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

```json theme={null}
GET https://ads-api.x.com/12/accounts?account_ids=18ce54d4x5t
```

**Example Response**

```json theme={null}
       {
         "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[](#get-accounts-account-id "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
       {
         "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[](#post-accounts "Permalink to this headline")

Note: **SANDBOX ONLY**

Create an ads account in the sandbox environment.

<Note type="warning">
  **SANDBOX ONLY**
</Note>

**Resource URL[](#resource-url "Permalink to this headline")**

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

**Parameters**

None

**Example Request**

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

**Example Response**

```json theme={null}
       {
         "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[](#put-accounts-account-id "Permalink to this headline")

Updates the account name and/or industry type.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="name" type="string" optional>
  The name of the account.
</ParamField>

<ParamField query="industry_type" type="string" optional>
  Industry that the account is associated with.
  <br /><br />Possible values: `AGENCY`, `BUSINESS_TO_BUSINESS`, `ONLINE_SERVICES`, `EDUCATION`, `FINANCIAL`, `HEALTH`, `GOVERNMENT`, `MEDIA`, `MOBILE`, `RESTAURANT`, `RETAIL`, `TECHNOLOGY`, `TRAVEL`, `OTHER`
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
       {
         "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[](#delete-accounts-account-id "Permalink to this headline")

<Note type="warning">
  **SANDBOX ONLY**
</Note>

Delete an ads account in the sandbox environment.

**Resource URL[](#resource-url "Permalink to this headline")**

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

**Parameters**

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
       {
         "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 ❯](https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87)

#### GET account\_apps[](#get-account-apps "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

**Parameters[](#parameters "Permalink to this headline")**

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request. Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.
  <br /><br />**Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
       {
         "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/account\_history[](#get-accounts-account-id-account-history "Permalink to this headline")

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

<Note type="warning">
  This endpoint is currently in beta and requires allowlisting.
</Note>

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="entity_type" type="string" required>
  The entity type to retrieve data for.<br /><br />
  Possible values: `CAMPAIGN`, `LINE_ITEM`, `PROMOTED_TWEET`, `TARGETING_CRITERIA`, `PROMOTED_ACCOUNT`
</ParamField>

<ParamField query="entity_id" type="string" required>
  The specific entity to retrieve data for.
</ParamField>

<ParamField query="start_time" type="string" required>
  Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />
  **Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
</ParamField>

<ParamField query="end_time" type="string" required>
  Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />
  **Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
</ParamField>

<ParamField query="user_id" type="long" optional>
  Scopes the response to a specific user.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET advertiser\_business\_categories[](#get-advertiser-business-categories "Permalink to this headline")

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

Each `advertiser_business_categories` represents a collection of [IAB Categories](/x-ads-api/campaign-management/reference#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](/x-ads-api/campaign-management/reference#line-items) endpoint to the set of corresponding `iab_categories` available through this endpoint.

Additional details can be found in the [Video Views Preroll Objective Guide](/x-ads-api/campaign-management/reference#video-views-preroll-objective)

**Resource URL[](#resource-url "Permalink to this headline")**

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

**Parameters[](#parameters "Permalink to this headline")**

No request parameters

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

POST accounts/:account\_id/audience\_estimate[](#post-accounts-account-id-audience-estimate "Permalink to this headline")

#### 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](/x-ads-api/campaign-management/reference#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](/x-ads-api/campaign-management/reference#targeting).

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField body="targeting_criteria" type="array" required>
  An array of targeting criteria objects. A list of required and optional targeting criteria parameters are available on the POST targeting criteria endpoint.
</ParamField>

<ParamField query="operator_type" type="string" default="EQ">
  Specify the relationship that the targeting criterion should have. For example, to set negated targeting, use `operator_type=NE`.<br /><br />
  Possible values: `EQ`, `NE`
</ParamField>

**Example Request**

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

```json theme={null}
    {
        "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**

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

### Authenticated User Access

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/authenticated\_user\_access[](#get-accounts-account-id-authenticated-user-access "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

**Parameters[](#parameters "Permalink to this headline")**

None

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "data": {
        "user_id": "2417045708",
        "permissions": [
          "ACCOUNT_ADMIN",
          "TWEET_COMPOSER"
        ]
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      }
    }
```

### Bidding Rules

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET bidding\_rules[](#get-bidding-rules "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField query="currency" type="string" optional>
  The type of a currency to filter results by, identified using [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217). This is a three-letter string "USD" or "EUR". Omit this parameter to retrieve all bidding rules associated with the authenticating user.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/campaigns[](#get-accounts-account-id-campaigns "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="campaign_ids" type="string" optional>
  Scope the response to just the desired campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="funding_instrument_ids" type="string" 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.
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope resource by `name`.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_draft" type="boolean" default="false">
  Include draft campaigns results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-accounts-account-id-campaigns-campaign-id "Permalink to this headline")

Retrieve a specific campaign associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="campaign_id" type="string" required>
  A reference to the campaign you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#post-accounts-account-id-campaigns "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="funding_instrument_id" type="string" required>
  The identifier for the funding instrument to create the campaign under.
</ParamField>

<ParamField query="name" type="string" required>
  The name for the campaign. Maximum length: 255 characters.
</ParamField>

<ParamField query="budget_optimization" type="string" default="CAMPAIGN">
  Select the type of budget optimization to be applied.<br /><br />
  Possible values: `CAMPAIGN`, `LINE_ITEM`
</ParamField>

<ParamField query="daily_budget_amount_local_micro" type="long" 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.<br /><br />
  **Note**: This should be less than or equal to the `total_budget_amount_local_micro` and is required for most Funding Instrument types.
</ParamField>

<ParamField query="entity_status" type="string" default="ACTIVE">
  The campaign status.<br /><br />
  Possible values: `ACTIVE`, `DRAFT`, `PAUSED`
</ParamField>

<ParamField query="purchase_order_number" type="string" optional>
  The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters.
</ParamField>

<ParamField query="standard_delivery" type="boolean" default="true">
  Enable standard or accelerated delivery. See [Budget Pacing](/x-ads-api/campaign-management/reference#budget-pacing) for more information on standard versus accelerated delivery. Only available when `budget_optimization` is set to `CAMPAIGN`.
</ParamField>

<ParamField query="total_budget_amount_local_micro" type="long" 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.
</ParamField>

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

```json theme={null}
    {
      "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[](#post-batch-accounts-account-id-campaigns "Permalink to this headline")

Allows the batch creation of new [campaigns](#post-accounts-account-id-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[](#resource-url "Permalink to this headline")**

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

<ParamField body="operation_type" type="string" required>
  The per item operation type being performed.<br /><br />
  Possible values: `Create`, `Delete`, `Update`
</ParamField>

<ParamField body="params" type="object" required>
  A JSON object containing all the parameters for the campaign objects. For a list of required and optional campaign parameters, see the single POST endpoint above.
</ParamField>

**Example Request**

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

```json theme={null}
    [
      {
        "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**

```json theme={null}
    {
      "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[](#put-accounts-account-id-campaigns-campaign-id "Permalink to this headline")

Update the specified campaign associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="campaign_id" type="string" required>
  A reference to the campaign you are operating with in the request.
</ParamField>

<ParamField query="budget_optimization" type="string" default="CAMPAIGN">
  Select the type of budget optimization to be applied.<br /><br />
  Possible values: `CAMPAIGN`, `LINE_ITEM`
</ParamField>

<ParamField query="daily_budget_amount_local_micro" type="long" 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.<br /><br />
  **Note**: This should be less than or equal to the `total_budget_amount_local_micro`.
</ParamField>

<ParamField query="entity_status" type="string" optional>
  The campaign status.<br /><br />
  Possible values: `ACTIVE`, `PAUSED`
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the campaign. Maximum length: 255 characters.
</ParamField>

<ParamField query="purchase_order_number" type="string" optional>
  The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters.
</ParamField>

<ParamField query="standard_delivery" type="boolean" default="true">
  Enable standard or accelerated delivery. See [Budget Pacing](/x-ads-api/campaign-management/reference#budget-pacing) for more information on standard versus accelerated delivery. Only available when `budget_optimization` is set to `CAMPAIGN`.
</ParamField>

<ParamField query="total_budget_amount_local_micro" type="long" 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.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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-accounts-account-id-campaigns-campaign-id "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="campaign_id" type="string" required>
  A reference to the campaign you are operating with in the request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET content\_categories[](#get-content-categories "Permalink to this headline")

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](/x-ads-api/campaign-management/reference#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](/x-ads-api/campaign-management/reference#publishers) endpoint.

Additional details can be found in the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management/reference#video-views-preroll-objective).

**Resource URL[](#resource-url "Permalink to this headline")**

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

**Parameters[](#parameters "Permalink to this headline")**

No request parameters

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/curated\_categories[](#get-accounts-account-id-curated-categories "Permalink to this headline")

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](/x-ads-api/campaign-management/reference#video-views-preroll-objective).

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="country_codes" type="string" 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.
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-accounts-account-id-curated-categories-curated-category-id "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="curated_category_id" type="string" required>
  A reference to the Curated Category you are operating with in the request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/features[](#get-accounts-account-id-features "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="feature_keys" type="string" optional>
  An optional parameter that enables querying for a specific feature key. Requests may include multiple comma-separated keys.<br /><br />
  **Note**: Only the features that are accessible by this account will be included in the response.<br /><br />
  Possible values: `REACH_AND_FREQUENCY_ANALYTICS`, `REACH_FREQUENCY_CAP`, `WEBSITE_CLICKS_CPM_BILLING`
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#post-accounts-account-id-features "Permalink to this headline")

**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](#get-accounts-account-id-features) endpoint.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="feature_keys" type="string" required>
  A comma-separated list of account features to add to the account.<br /><br />
  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`
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#delete-accounts-account-id-features "Permalink to this headline")

**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](#get-accounts-account-id-features) endpoint.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="feature_keys" type="string" required>
  A comma-separated list of account features to remove from the account.<br /><br />
  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`
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/funding\_instruments[](#get-accounts-account-id-funding-instruments "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request. Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="funding_instrument_ids" type="string" 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.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-accounts-account-id-funding-instruments-funding-instrument-id "Permalink to this headline")

Retrieve a specific funding instrument associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="funding_instrument_id" type="string" required>
  A reference to the funding instrument you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#post-accounts-account-id-funding-instruments "Permalink to this headline")

**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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="currency" type="string" required>
  The currency, expressed in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217).
</ParamField>

<ParamField query="start_time" type="string" required>
  The date for the funding instrument to become active and usable, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
</ParamField>

<ParamField query="type" type="string" required>
  The type of funding instrument to create.<br /><br />
  Possible values: `AGENCY_CREDIT_LINE`, `CREDIT_CARD`, `CREDIT_LINE`, `INSERTION_ORDER`, `PARTNER_MANAGED`
</ParamField>

<ParamField query="end_time" type="string" optional>
  The date for the funding instrument to become inactive, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
</ParamField>

<ParamField query="credit_limit_local_micro" type="long" optional>
  The total credit available against this funding instrument.<br /><br />
  **Note**: Only applicable to some funding instrument types.
</ParamField>

<ParamField query="funded_amount_local_micro" type="long" optional>
  The total budget amount allocated to this funding instrument.<br /><br />
  **Note**: Only applicable to some funding instrument types.
</ParamField>

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

```json theme={null}
    {
      "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[](#delete-accounts-account-id-funding-instruments-funding-instrument-id "Permalink to this headline")

**SANDBOX ONLY**

Delete a funding instrument in the sandbox environment.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="funding_instrument_id" type="string" required>
  A reference to the funding instrument you are operating with in the request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET iab\_categories[](#get-iab-categories "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of categories. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/line\_items[](#get-accounts-account-id-line-items "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="campaign_ids" type="string" 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.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="funding_instrument_ids" type="string" 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.
</ParamField>

<ParamField query="line_item_ids" type="string" 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.
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope resource by `name`.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_draft" type="boolean" default="false">
  Include draft campaigns results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-accounts-account-id-line-items-line-item-id "Permalink to this headline")

Retrieve a specific line item associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="line_item_id" type="string" required>
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#post-accounts-account-id-line-items "Permalink to this headline")

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](/x-ads-api/campaign-management/reference#targeting-options) for `iOS`.

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="campaign_id" type="string" required>
  The identifier for the campaign to create the line item under.
</ParamField>

<ParamField query="end_time" type="string" required>
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will stop serving.
</ParamField>

<ParamField query="objective" type="string" required>
  The campaign objective for this line item.<br /><br />
  Possible values: `APP_ENGAGEMENTS`, `APP_INSTALLS`, `REACH`, `FOLLOWERS`, `ENGAGEMENTS`, `VIDEO_VIEWS`, `PREROLL_VIEWS`, `WEBSITE_CLICKS`
</ParamField>

<ParamField query="placements" type="string" required>
  The placement location(s) for this line item to display in. Specify a comma-separated list of placement values.<br /><br />
  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`
</ParamField>

<ParamField query="product_type" type="string" required>
  The type of promoted product that this line item will contain.<br /><br />
  Possible values: `MEDIA`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEETS`
</ParamField>

<ParamField query="start_time" type="string" required>
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.
</ParamField>

<ParamField query="advertiser_domain" type="string" optional>
  The website domain for this advertiser, without the protocol specification.<br /><br />
  **Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.
</ParamField>

<ParamField query="android_app_store_identifier" type="string" optional>
  The Google App Store identifier for promoted applications.<br /><br />
  **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`.
</ParamField>

<ParamField query="bid_amount_local_micro" type="long" 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.<br /><br />
  **Note**: Required if `bid_strategy` is set to either `MAX` or `TARGET`. Only values greater than zero are accepted.
</ParamField>

<ParamField query="categories" type="string" optional>
  The relevant IAB categories for this advertiser. See [GET iab\_categories](/x-ads-api/campaign-management/reference#iab-categories).<br /><br />
  **Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.
</ParamField>

<ParamField query="ios_app_store_identifier" type="string" optional>
  The numeric portion of the Apple App Store identifier for promoted applications.<br /><br />
  **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`.
</ParamField>

<ParamField query="primary_web_event_tag" type="string" optional>
  The identifier of the primary web event tag. Allows more accurate tracking of engagements for the campaign pertaining to this line item.<br /><br />
  **Note**: Required when the line item's goal is set to `WEBSITE_CONVERSIONS`.
</ParamField>

<ParamField query="advertiser_user_id" type="string" optional>
  The X user identifier for the handle promoting a `PREROLL_VIEWS` ad. Only certain client applications may use this parameter.
</ParamField>

<ParamField query="audience_expansion" type="string" optional>
  Used to expand the reach of campaigns by targeting users similar to those already targeted.<br /><br />
  **Note**: By default, no expansion will be applied.<br /><br />
  Possible values: `BROAD`, `DEFINED`, `EXPANDED`
</ParamField>

<ParamField query="bid_strategy" type="string" optional>
  The bidding mechanism.<br /><br />
  `AUTO` automatically optimizes bidding based on daily budget and campaign flight dates.<br />
  `MAX` sets the maximum allowable bid and is **not** available when the objective is set to `REACH` or `FOLLOWERS`.<br />
  `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`.<br /><br />
  **Note**: If set to `AUTO`, `bid_amount_local_micro` will be ignored.<br />
  **Note**: Default based on objective.<br /><br />
  Possible values: `AUTO`, `MAX`, `TARGET`
</ParamField>

<ParamField query="duration_in_days" type="int" optional>
  The time period within which the `frequency_cap` is achieved.<br /><br />
  Possible values: `1`, `7`, `30`
</ParamField>

<ParamField query="entity_status" type="string" optional>
  The line item status.<br /><br />
  Possible values: `ACTIVE`, `DRAFT`, `PAUSED`
</ParamField>

<ParamField query="frequency_cap" type="int" optional>
  The maximum number of times an ad could be delivered to a user.<br /><br />
  **Note**: Only supported for `REACH`, `ENGAGEMENTS`, `VIDEO_VIEWS`, and `PREROLL_VIEWS` objectives.
</ParamField>

<ParamField query="goal" type="string" optional>
  The optimization setting to use with this line item.<br /><br />
  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](https://business.x.com/en/help/campaign-setup/create-an-app-installs-or-app-engagement-campaign/mobile-app-conversion-tracking.html).<br /><br />
  The `SITE_VISITS` option is only available with the `WEBSITE_CLICKS` objective.<br /><br />
  **Note**: Default based on objective.<br /><br />
  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`
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the line item.<br /><br />
  Min, Max length: 1, 255
</ParamField>

<ParamField query="pay_by" type="string" optional>
  The unit to charge this line item by. This setting can only be modified for line items using the `APP_INSTALLS` objective.<br /><br />
  **Note**: The default `pay_by` is automatically set based upon the campaign objective and line item's bid unit.<br /><br />
  The `APP_INSTALLS` goal supports both `APP_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value.<br />
  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`.<br />
  The `SITE_VISITS` goal supports `IMPRESSION` values.<br /><br />
  Possible values: `APP_CLICK`, `IMPRESSION`, `LINK_CLICK`
</ParamField>

<ParamField query="standard_delivery" type="boolean" optional>
  Enable standard or accelerated delivery. See [Budget Pacing](/x-ads-api/campaign-management/reference#budget-pacing) for more information on standard versus accelerated delivery. Only available when `budget_optimization` is set to `LINE_ITEM` for the parent campaign.
</ParamField>

<ParamField query="total_budget_amount_local_micro" type="long" 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.
</ParamField>

<ParamField query="daily_budget_amount_local_micro" type="long" 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.<br /><br />
  **Note**: This should be less than or equal to the `total_budget_amount_local_micro`.
</ParamField>

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

```json theme={null}
    {
      "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[](#post-batch-accounts-account-id-line-items "Permalink to this headline")

Allows the batch creation of new [line items](#post-accounts-account-id-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[](#resource-url "Permalink to this headline")**

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

<ParamField body="operation_type" type="string" required>
  The per item operation type being performed.<br /><br />
  Possible values: `Create`, `Delete`, `Update`
</ParamField>

<ParamField body="params" type="object" required>
  A JSON object containing all the parameters for the line item objects. For a list of required and optional line item parameters, see the single POST endpoint above.
</ParamField>

**Example Request**

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

```json theme={null}
    [
      {
        "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**

```json theme={null}
    {
      "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[](#put-accounts-account-id-line-items-line-item-id "Permalink to this headline")

Update the specified line item associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="line_item_id" type="string" required>
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField query="advertiser_domain" type="string" optional>
  The website domain for this advertiser, without the protocol specification.<br /><br />
  **Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.
</ParamField>

<ParamField query="advertiser_user_id" type="string" optional>
  The Twitter user identifier for the handle promoting a `PREROLL_VIEWS` ad. Only certain client applications may use this parameter.
</ParamField>

<ParamField query="android_app_store_identifier" type="string" optional>
  The Google App Store identifier for the promoted application.<br /><br />
  **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`.
</ParamField>

<ParamField query="audience_expansion" type="string" optional>
  Used to expand the reach of campaigns by targeting users similar to those already targeted.<br /><br />
  Possible values: `BROAD`, `DEFINED`, `EXPANDED`
</ParamField>

<ParamField query="bid_amount_local_micro" type="long" 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.<br /><br />
  **Note**: Required if `bid_strategy` is set to either `MAX` or `TARGET`. Only values greater than zero are accepted.
</ParamField>

<ParamField query="bid_strategy" type="string" optional>
  The bidding mechanism.<br /><br />
  `AUTO` automatically optimizes bidding based on daily budget and campaign flight dates.<br />
  `MAX` sets the maximum allowable bid and is **not** available when the objective is set to `REACH` or `FOLLOWERS`.<br />
  `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`.<br /><br />
  **Note**: If set to `AUTO`, `bid_amount_local_micro` will be ignored.<br />
  **Note**: Default based on objective.<br /><br />
  Possible values: `AUTO`, `MAX`, `TARGET`
</ParamField>

<ParamField query="categories" type="string" optional>
  The relevant IAB categories for this advertiser. See [GET iab\_categories](/x-ads-api/campaign-management/reference#iab-categories).<br /><br />
  **Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.
</ParamField>

<ParamField query="duration_in_days" type="int" optional>
  The time period within which the `frequency_cap` is achieved.<br /><br />
  Possible values: `1`, `7`, `30`
</ParamField>

<ParamField query="entity_status" type="string" optional>
  The line item status.<br /><br />
  Possible values: `ACTIVE`, `PAUSED`
</ParamField>

<ParamField query="end_time" type="string" optional>
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will stop serving.
</ParamField>

<ParamField query="frequency_cap" type="int" optional>
  The maximum number of times an ad could be delivered to a user.<br /><br />
  **Note**: Only supported for `REACH`, `ENGAGEMENTS`, `VIDEO_VIEWS`, and `PREROLL_VIEWS` objectives.
</ParamField>

<ParamField query="goal" type="string" 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](https://business.x.com/en/help/campaign-setup/create-an-app-installs-or-app-engagement-campaign/mobile-app-conversion-tracking.html).<br /><br />
  **Note**: Default based on objective.<br /><br />
  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`
</ParamField>

<ParamField query="ios_app_store_identifier" type="string" optional>
  The numeric portion of the Apple App Store identifier for promoted applications.<br /><br />
  **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`.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the line item.
</ParamField>

<ParamField query="pay_by" type="string" optional>
  The unit to charge this line item by. This setting can only be modified for line items using the `APP_INSTALLS` objective.<br /><br />
  **Note**: The default `pay_by` is automatically set based upon the campaign objective and line item's bid unit.<br /><br />
  The `APP_INSTALLS` goal supports both `APP_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value.<br />
  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`.<br />
  The `SITE_VISITS` goal supports `IMPRESSION` values.<br /><br />
  Possible values: `APP_CLICK`, `IMPRESSION`, `LINK_CLICK`
</ParamField>

<ParamField query="start_time" type="string" optional>
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.
</ParamField>

<ParamField query="total_budget_amount_local_micro" type="long" 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.
</ParamField>

<ParamField query="daily_budget_amount_local_micro" type="long" 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.<br /><br />
  **Note**: This should be less than or equal to the `total_budget_amount_local_micro`.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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-accounts-account-id-line-items-line-item-id "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="line_item_id" type="string" required>
  A reference to the line item you are operating with in the request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

Additional details on usage can be found at the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management/reference#video-views-preroll-objective)

#### GET accounts/:account\_id/line\_item\_curated\_categories[](#get-accounts-account-id-line-item-curated-categories "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```josn theme={null}
    {
      "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[](#get-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline")

Retrieves details for a specific line item curated category associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="line_item_curated_category_id" type="string" required>
  A reference to the line item curated category you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#post-accounts-account-id-line-item-curated-categories "Permalink to this headline")

Associate a [curated category](/x-ads-api/campaign-management/reference#curated-categories-2) object with the specified line item.

**Resource URL[](#resource-url "Permalink to this headline")**

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

**Parameters[](#parameters "Permalink to this headline")**

| Name                                    | Description                                                                                                                                                                                                                                                                                                                                                         |
| :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id  <br />`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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.<br /><br />Type: string<br /><br />Example: `18ce54d4x5t` |
| curated\_category\_id  <br />`required` | A reference to the curated category entity you are operating with in the request.<br /><br />Type: string<br /><br />Example: `10miy`                                                                                                                                                                                                                               |
| line\_item\_id  <br />`required`        | A reference to the line item you are operating with in the request.<br /><br />Type: string<br /><br />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**

```json theme={null}
    {
      "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[](#put-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline")

Update the specified line item curated category.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="line_item_curated_category_id" type="string" required>
  A reference to the line item curated category you are operating with in the request.
</ParamField>

\| curated\_category\_id  <br />`optional` | A reference to the curated category entity you are operating with in the request.<br /><br />Type: string<br /><br />Example: `10miy` |
\| line\_item\_id  <br />`optional` | A reference to the line item you are operating with in the request.<br /><br />Type: string<br /><br />Example: `8v7jo` |

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline")

Delete the specified line item curated category.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="line_item_curated_category_id" type="string" required>
  A reference to the line item curated category you are operating with in the request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET line\_items/placements[](#get-line-items-placements "Permalink to this headline")

Retrieve valid `placement` and `product_type` combinations.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField query="product_type" type="enum" optional>
  Scope the response to just the valid placements for the specified product type.<br /><br />
  Possible values: `MEDIA`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEETS`
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "data": [
        {
          "product_type": "PROMOTED_ACCOUNT",
          "placements": [
            [
              "ALL_ON_TWITTER"
            ],
            [
              "TWITTER_TIMELINE"
            ]
          ]
        }
      ],
      "request": {
        "params": {
          "product_type": "PROMOTED_ACCOUNT"
        }
      }
    }
```

### Media Creatives

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/media\_creatives[](#get-accounts-account-id-media-creatives "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="campaign_id" type="string" optional>
  Scope the response to just the media creatives associated with the specified campaign.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="line_item_ids" type="string" 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.
</ParamField>

<ParamField query="media_creative_ids" type="string" 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.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-accounts-account-id-media-creatives-media-creative-id "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="media_creative_id" type="string" required>
  A reference to the media creative you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#post-accounts-account-id-media-creatives "Permalink to this headline")

Associate an [account media](/x-ads-api/creatives/reference#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](/x-ads-api/creatives/reference#account-media) endpoint.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="account_media_id" type="string" required>
  A reference to the account media entity you are operating with in the request.
</ParamField>

<ParamField query="line_item_id" type="string" required>
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField query="landing_url" type="string" optional>
  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](/x-ads-api/creatives/reference#post-accounts-account-id-preroll-call-to-actions) endpoint.<br /><br />
  **Note**: Required when the line item's objective is set to `WEBSITE_CLICKS`.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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-accounts-account-id-media-creatives-media-creative-id "Permalink to this headline")

Delete the specified media creative belonging to the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="media_creative_id" type="string" required>
  A reference to the media creative you are operating with in the request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/promoted\_accounts[](#get-accounts-account-id-promoted-accounts "Permalink to this headline")

Retrieve details for some or all promoted accounts associated with one or more line items under the current account.

Use [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="line_item_ids" type="string" 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.
</ParamField>

<ParamField query="promoted_account_ids" type="string" 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.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-accounts-account-id-promoted-accounts-promoted-account-id "Permalink to this headline")

Retrieve a specific reference to an account associated with a line item under the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="promoted_account_id" type="string" required>
  A reference to the promoted account you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#post-accounts-account-id-promoted-accounts "Permalink to this headline")

Associate an account (`user_id`) with the specified line item.

If the specified line item is not configured to be associated with Promoted Accounts, an HTTP 400 `INCOMPATIBLE_LINE_ITEM` error will be returned. If the specified user is ineligible for promotion, an HTTP 400 will be returned and no users will be promoted. If the provided user is already promoted, the request will be ignored.

For more information on Promoted Accounts, see our [campaign management](/x-ads-api/campaign-management/reference#advertiser-api) page.

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="line_item_id" type="string" required>
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField query="user_id" type="long" required>
  A reference to the user you are operating with in the request. Use [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) to retrieve a user ID for a screen name.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={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
      },
      "request": {
        "params": {
          "user_id": "756201191646691328",
          "line_item_id": "9bpb2",
          "account_id": "18ce54d4x5t"
        }
      }
    }
```

#### DELETE accounts/:account\_id/promoted\_accounts/:promoted\_account\_id[](#delete-accounts-account-id-promoted-accounts-promoted-account-id "Permalink to this headline")

Disassociate an account from the specified line item.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="promoted_account_id" type="string" required>
  The identifier refers to the instance of a Promoted Account associated with a line item.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/promoted\_tweets[](#get-accounts-account-id-promoted-tweets "Permalink to this headline")

Retrieve references to Tweets associated with line items under the current account.

Use the [GET accounts/:account\_id/tweets](/x-ads-api/creatives/reference#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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="line_item_ids" type="string" 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.
</ParamField>

<ParamField query="promoted_tweet_ids" type="string" 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.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-accounts-account-id-promoted-tweets-promoted-tweet-id "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="promoted_tweet_id" type="string" required>
  A reference to the promoted Tweet you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#post-accounts-account-id-promoted-tweets "Permalink to this headline")

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](/x-ads-api/campaign-management/reference#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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="line_item_id" type="string" required>
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField query="tweet_ids" type="string" required>
  A comma-separated list of identifiers corresponding to specific Tweets. Up to 50 IDs may be provided.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#delete-accounts-account-id-promoted-tweets-promoted-tweet-id "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="promoted_tweet_id" type="string" 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](#get-accounts-account-id-promoted-tweets), not the `tweet_id` of the Tweet in question. Supplied within the resource's path.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/promotable\_users[](#get-accounts-account-id-promotable-users "Permalink to this headline")

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](/x-ads-api/campaign-management/reference#promoted-tweets) endpoint to promote published Tweets and the [POST accounts/:account\_id/scheduled-promoted-tweets](/x-ads-api/campaign-management/reference#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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="promotable_user_ids" type="string" 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.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-accounts-account-id-promotable-users-promotable-user-id "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="promotable_user_id" type="string" optional>
  A reference to the promotable user you are operating on within the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET publishers[](#get-publishers "Permalink to this headline")

Retrieve a list of Content Category publishers' details

Additional details can be found in the [Video Views Preroll Objective Guide](/x-ads-api/campaign-management/reference#video-views-preroll-objective)

**Resource URL[](#resource-url "Permalink to this headline")**

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

**Parameters[](#parameters "Permalink to this headline")**

No request parameters

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/369a02c0adc626ff6a06#?env%5BTwitter%20Ads%20API%5D=W3sia2V5IjoiYWNjb3VudF9pZCIsInZhbHVlIjoieW91cl9hZHNfYWNjb3VudF9pZCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidmVyc2lvbiIsInZhbHVlIjoiNSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfa2V5IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX2tleSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfc2VjcmV0IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX3NlY3JldCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYWNjZXNzX3Rva2VuIiwidmFsdWUiOiJ5b3VyX2FjY2Vzc190b2tlbiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidG9rZW5fc2VjcmV0IiwidmFsdWUiOiJ5b3VyX3Rva2VuX3NlY3JldCIsImVuYWJsZWQiOnRydWV9XQ==">
  Run in Postman
</Button>

#### GET accounts/:account\_id/recommendations[](#get-accounts-account-id-recommendations "Permalink to this headline")

Status: *Closed Beta*

Retrieve campaign recommendations associated with this ads account. Currently there is a limit of 1 recommendation per funding instrument.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    "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[](#get-accounts-account-id-recommendations-recommendation-id "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="recommendation_id" type="string" required>
  A reference to the recommendation ID you are operating within the request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
    "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/scheduled\_promoted\_tweets[](#get-accounts-account-id-scheduled-promoted-tweets "Permalink to this headline")

Retrieve details for some or all scheduled promoted Tweets associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="line_item_ids" type="string" 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.
</ParamField>

<ParamField query="scheduled_promoted_tweet_ids" type="string" 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.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="scheduled_promoted_tweet_id" type="string" required>
  A reference to the scheduled promoted Tweet you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#post-accounts-account-id-scheduled-promoted-tweets "Permalink to this headline")

Associate a scheduled Tweet with the specified line item.

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="line_item_id" type="string" required>
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField query="scheduled_tweet_id" type="long" required>
  A reference to the scheduled Tweet you are operating with in the request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="scheduled_promoted_tweet_id" type="string" 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](#get-accounts-account-id-scheduled-promoted-tweets) response object.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/targeting\_criteria[](#get-accounts-account-id-targeting-criteria "Permalink to this headline")

Retrieve details for some or all of the targeting criteria associated with line items under the current account.

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="line_item_ids" type="string" 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.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="lang" type="string" optional>
  An [ISO-639-1](https://en.wikipedia.org/wiki/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.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="targeting_criterion_ids" type="string" 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.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-accounts-account-id-targeting-criteria-targeting-criterion-id "Permalink to this headline")

Retrieve a specific targeting criterion associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="targeting_criterion_id" type="string" required>
  A reference to the targeting criterion you are operating with in the request.
</ParamField>

<ParamField query="lang" type="string" optional>
  An [ISO-639-1](https://en.wikipedia.org/wiki/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.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#post-accounts-account-id-targeting-criteria "Permalink to this headline")

See the [Targeting Options](/x-ads-api/campaign-management/reference#targeting-options) page to find `targeting_value`s for specific targeting types. We recommend that you refresh all data weekly, to ensure that you are working with the latest set of targeting type values. We change values and available targeting criteria from time to time; while the majority of these don't change often, some do. There is no guarantee that these values will not change.

Use the `BROAD_KEYWORD`, `EXACT_KEYWORD`, `PHRASE_KEYWORD`, or `UNORDERED_KEYWORD` targeting types with the keywords specified in the `targeting_value`. Exclude keywords by using the `operator_type` request parameter set to `NE`. See [targeting keyword types](/x-ads-api/campaign-management/reference#targeting) 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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="line_item_id" type="string" required>
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField query="operator_type" type="enum" required>
  Specify the relationship that the targeting criterion should have. For example, to exclude keywords, use `operator_type=NE`.<br /><br />
  Possible values: `EQ`, `NE`, `GTE`, `LT`
</ParamField>

<ParamField query="targeting_type" type="string" required>
  The type of targeting that will be applied to this line item.<br /><br />
  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`.<br /><br />
  **Note**: It is only possible to target a single `AGE` bucket per line item.<br /><br />
  Possible keyword-based values include: `BROAD_KEYWORD`, `EXACT_KEYWORD`, `PHRASE_KEYWORD`, `UNORDERED_KEYWORD`.<br /><br />
  Possible custom audience values include: `CUSTOM_AUDIENCE`, `CUSTOM_AUDIENCE_EXPANDED`.<br /><br />
  Possible installed app store category values: `APP_STORE_CATEGORY`, `APP_STORE_CATEGORY_LOOKALIKE`.<br /><br />
  Possible Twitter Audience Platform (TAP) app exclusion: `APP_LIST` (may only be used with `operator_type=NE`).
</ParamField>

<ParamField query="targeting_value" type="string" 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.
</ParamField>

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

```json theme={null}
    {
      "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[](#post-batch-accounts-account-id-targeting-criteria "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField query="operation_type" type="enum" required>
  The per item operation type being performed.<br /><br />
  Possible values: `Create`, `Delete`
</ParamField>

<ParamField query="params" type="object" 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](#post-accounts-account-id-targeting-criteria).<br /><br />
  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.
</ParamField>

**Example Request**

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

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

**Example Response**

```json theme={null}
    {
      "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-accounts-account-id-targeting-criteria-targeting-criterion-id "Permalink to this headline")

Delete the specified targeting criterion belonging to the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="targeting_criterion_id" type="string" required>
  A reference to the targeting criterion you are operating with in the request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

* [App Store Categories](#get-targeting-criteria-app-store-categories)
* [Conversation](#get-targeting-criteria-conversations)
* [Devices](#get-targeting-criteria-devices)
* [Events](#get-targeting-criteria-events)
* [Interests](#get-targeting-criteria-interests)
* [Languages](#get-targeting-criteria-languages)
* [Locations](#get-targeting-criteria-locations)
* [Network Operators](#get-targeting-criteria-network-operators)
* [Platform Versions](#get-targeting-criteria-platform-versions)
* [Platforms](#get-targeting-criteria-platforms)
* [TV Markets](#get-targeting-criteria-tv-markets)
* [TV Shows](#get-targeting-criteria-tv-shows)

#### GET targeting\_criteria/app\_store\_categories[](#get-targeting-criteria-app-store-categories "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField query="q" type="string" optional>
  An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
</ParamField>

<ParamField query="os_type" type="enum" optional>
  Scope the results by a specific app store.<br /><br />
  Possible values: `ANDROID`, `IOS`
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-targeting-criteria-conversations "Permalink to this headline")

Discover available conversation-based targeting criteria for Promoted Products.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField query="conversation_type" type="enum" optional>
  An optional query to scope to a certain conversation type.<br /><br />
  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`
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-targeting-criteria-devices "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-targeting-criteria-events "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField query="event_types" type="enum" required>
  An optional query to scope to certain event types.<br /><br />
  Possible values: `CONFERENCE`, `HOLIDAY`, `MUSIC_AND_ENTERTAINMENT`, `OTHER`, `POLITICS`, `RECURRING`, `SPORTS`
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="country_codes" type="string" 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.
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="end_time" type="string" optional>
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the campaign will end.
</ParamField>

<ParamField query="start_time" type="string" optional>
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.<br /><br />
  **Note**: Defaults to the current time.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-targeting-criteria-interests "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-targeting-criteria-languages "Permalink to this headline")

Discover languages available for targeting.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope a targeting criteria. Omit this parameter to retrieve all.
</ParamField>

**Example Request**

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

**Example Response**

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

#### GET targeting\_criteria/locations[](#get-targeting-criteria-locations "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="country_code" type="string" 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.
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="location_type" type="enum" optional>
  Scope the results by a specific kind of location. More granular targeting than `COUNTRIES` may not be available in all locations.<br /><br />
  Possible values: `COUNTRIES`, `REGIONS`, `METROS`, `CITIES`, `POSTAL_CODES`
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-targeting-criteria-network-operators "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="country_code" type="string" default="US">
  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.
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-targeting-criteria-platform-versions "Permalink to this headline")

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[](#resource-url "Permalink to this headline")**

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

<ParamField query="q" type="string" optional>
  An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
        "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[](#get-targeting-criteria-platforms "Permalink to this headline")

Discover available platform-based targeting criteria for Promoted Products.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
</ParamField>

<ParamField query="lang" type="string" optional>
  Using a [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code. When passed, an additional localized\_name attribute will be returned in the response.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-targeting-criteria-tv-markets "Permalink to this headline")

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](/x-ads-api/campaign-management/reference#get-targeting-criteria-tv-shows) endpoint.

**Resource URL[](#resource-url "Permalink to this headline")**

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

**Parameters[](#parameters "Permalink to this headline")**

None

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-targeting-criteria-tv-shows "Permalink to this headline")

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](/x-ads-api/campaign-management/reference#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[](#resource-url "Permalink to this headline")**

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

<ParamField query="locale" type="string" 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](/x-ads-api/campaign-management/reference#get-targeting-criteria-tv-markets).
</ParamField>

<ParamField query="count" type="int" default="50">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 50
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
</ParamField>

**Example Request**

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

**Example Response**

```jdon theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/targeting\_suggestions[](#get-accounts-account-id-targeting-suggestions "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="suggestion_type" type="enum" required>
  Specify the type of suggestions to return.<br /><br />
  Possible values: `KEYWORD`, `USER_ID`
</ParamField>

<ParamField query="targeting_values" type="string" required>
  Comma separated collection of either keywords or user IDs used to seed the suggestions.<br /><br />
  **Note**: These two types of suggestions cannot be mixed.
</ParamField>

<ParamField query="count" type="int" default="30">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 50
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/tax\_settings[](#get-accounts-account-id-tax-settings "Permalink to this headline")

Retrieve tax setting details associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#put-accounts-account-id-tax-settings "Permalink to this headline")

Update the tax settings for the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="address_city" type="string" optional>
  The city for the account owner's address.
</ParamField>

<ParamField query="address_country" type="string" optional>
  The two-letter country code for the account owner's address.
</ParamField>

<ParamField query="address_email" type="string" optional>
  The email associated with the account owner's address.
</ParamField>

<ParamField query="address_first_name" type="string" optional>
  The first name for the account owner's address.
</ParamField>

<ParamField query="address_last_name" type="string" optional>
  The last name for the account owner's address.
</ParamField>

<ParamField query="address_name" type="string" optional>
  The company name for the account owner's address.
</ParamField>

<ParamField query="address_postal_code" type="string" optional>
  The postal code for the account owner's address.
</ParamField>

<ParamField query="address_region" type="string" optional>
  The region for the account owner's address.
</ParamField>

<ParamField query="address_street1" type="string" optional>
  The street line for the account owner's address.
</ParamField>

<ParamField query="address_street2" type="string" optional>
  The second street line for the account owner's address.
</ParamField>

<ParamField query="bill_to" type="enum" optional>
  The entity that is billed.<br /><br />
  Possible values: `ADVERTISER`, `AGENCY`
</ParamField>

<ParamField query="business_relationship" type="enum" optional>
  Whether the account is owned by the advertiser or by the agency.<br /><br />
  Possible values: `AGENCY`, `SELF`
</ParamField>

<ParamField query="client_address_city" type="string" optional>
  The city for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField query="client_address_country" type="string" optional>
  The two-letter country code for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField query="client_address_email" type="string" optional>
  The email associated with the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField query="client_address_first_name" type="string" optional>
  The first name for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField query="client_address_last_name" type="string" optional>
  The last name for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField query="client_address_name" type="string" optional>
  The company name for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField query="client_address_postal_code" type="string" optional>
  The postal code for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField query="client_address_region" type="string" optional>
  The region for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField query="client_address_street1" type="string" optional>
  The street line for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField query="client_address_street2" type="string" optional>
  The second street line for the advertiser's address.<br /><br />
  Set this when the ads account is owned by an agency.
</ParamField>

<ParamField query="invoice_jurisdiction" type="enum" optional>
  Invoice jurisdiction.<br /><br />
  Possible values: `LOI_SAPIN`, `NONE`, `NOT_SET`
</ParamField>

<ParamField query="tax_category" type="enum" optional>
  Whether the taxation should be individual or business.<br /><br />
  Possible values: `BUSINESS_NO_VAT`, `BUSINESS_WITH_VAT`, `INDIVIDUAL`
</ParamField>

<ParamField query="tax_exemption_id" type="string" optional>
  VAT exemption ID.
</ParamField>

<ParamField query="tax_id" type="string" optional>
  VAT registration ID.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/tracking\_tags[](#get-accounts-account-id-tracking-tags "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="line_item_ids" type="string" 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.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="tracking_tag_ids" type="string" 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.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#get-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline")

Retrieve a specific tracking tag associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="tracking_tag_id" type="string" required>
  A reference to the tracking tag you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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[](#post-accounts-account-id-tracking-tags "Permalink to this headline")

Associate a tracking tag with the specified line item.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="line_item_id" type="string" required>
  A reference to the line item you are operating with in the request.
</ParamField>

<ParamField query="tracking_tag_type" type="enum" required>
  The type of tracking tag.<br /><br />
  Possible value: `IMPRESSION_TAG`, `CLICK_TRACKER`
</ParamField>

<ParamField query="tracking_tag_url" type="string" required>
  The tracking tag url provided by the tracking partner.
</ParamField>

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

```json theme={null}
    {
      "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[](#put-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline")

Associate a tracking tag with the specified line item.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="tracking_tag_url" type="string" required>
  The tracking tag url provided by the tracking partner.
</ParamField>

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

```json theme={null}
    {
      "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[](#delete-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline")

Disassociate a tracking tag from the specified line item.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="tracking_tag_id" type="string" required>
  A reference to the tracking tag you are operating with in the request.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
    {
      "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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

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

#### GET accounts/:account\_id/user\_settings/:user\_id[](#get-accounts-account-id-user-settings-user-id "Permalink to this headline")

Retrieves user settings.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="user_id" type="long" 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.
</ParamField>

**Example Request**

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

**Example Response**

```json theme={null}
      {
        "request": {
          "params": {
            "account_id": "18ce54d4x5t",
            "user_id": "756201191646691328"
          }
        },
        "data": {
          "notification_email": "user@domain.com",
          "contact_phone": "",
          "contact_phone_extension": ""
        }
      }
```

#### PUT accounts/:account\_id/user\_settings/:user\_id[](#put-accounts-account-id-user-settings-user-id "Permalink to this headline")

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

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="user_id" type="long" 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.
</ParamField>

<ParamField query="notification_email" type="string" optional>
  Email to use for account notifications.
</ParamField>

<ParamField query="contact_phone" type="string" optional>
  Contact phone number.
</ParamField>

<ParamField query="contact_phone_extension" type="string" optional>
  Extension for contact `contact_phone`.
</ParamField>

**Example Request**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328?notification_email='user@domain.com'&subscribe_email_types=ACCOUNT_PERFORMANCE,PERFORMANCE_IMPROVEMENT"`

**Example Response**

```json theme={null}
      {
        "request": {
          "params": {
            "account_id": "18ce54d4x5t",
            "user_id": "756201191646691328"
            "notification_email": "user@domain.com",
            "subscribed_campaign_events": [
              "ACCOUNT_PERFORMANCE",
              "PERFORMANCE_IMPROVEMENT"
            ]
          }
        },
        "data": {
          "notification_email": "user@domain.com",
          "contact_phone": "",
          "Contact_phone_extension": ""
        }
      }
```