Campaign Management

Line Items¶

GET accounts/:account_id/line_items¶

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

Resource URL¶

https://ads-api.twitter.com/4/accounts/:account_id/line_items

Parameters¶

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

Example Request¶

GET https://ads-api.twitter.com/4/accounts/18ce54d4x5t/line_items?line_item_ids=8v7jo

Example Response¶

{
  "request": {
    "params": {
      "line_item_ids": [
        "8v7jo"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "bid_type": "MAX",
      "advertiser_user_id": 756201191646691328,
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "start_time": null,
      "bid_amount_local_micro": 100000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "target_cpa_local_micro": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "end_time": null,
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": null,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "8v7jo",
      "entity_status": "ACTIVE",
      "account_id": "18ce54d4x5t",
      "optimization": "DEFAULT",
      "categories": [],
      "currency": "USD",
      "created_at": "2017-05-27T08:04:00Z",
      "tracking_tags": [],
      "updated_at": "2017-05-27T08:06:25Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "8gdx6",
      "creative_source": "MANUAL",
      "deleted": false
    }
  ]
}

GET accounts/:account_id/line_items/:line_item_id¶

Retrieve a specific line item associated with the current account.

Resource URL¶

https://ads-api.twitter.com/4/accounts/:account_id/line_items/:line_item_id

Parameters¶

Name Description

account_id

required

The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

line_item_id

required

A reference to the line item you are operating with in the request.

Type: string

Example: 8v7jo

with_deleted

optional

Include deleted results in your request.

Type: boolean

Default: false

Possible values: true, false

Example Request¶

GET https://ads-api.twitter.com/4/accounts/18ce54d4x5t/line_items/8v7jo

Example Response¶

{
  "request": {
    "params": {
      "line_item_id": "8v7jo",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "bid_type": "MAX",
    "advertiser_user_id": 756201191646691328,
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "start_time": null,
    "bid_amount_local_micro": 100000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "target_cpa_local_micro": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "end_time": null,
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "TWEET_ENGAGEMENTS",
    "id": "8v7jo",
    "entity_status": "ACTIVE",
    "account_id": "18ce54d4x5t",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2017-05-27T08:04:00Z",
    "tracking_tags": [],
    "updated_at": "2017-05-27T08:06:25Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "8gdx6",
    "creative_source": "MANUAL",
    "deleted": false
  }
}

POST accounts/:account_id/line_items¶

Create a line item associated with the specified campaign belonging to the current account.

All line items within a campaign must be of the same product_type and objective.

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

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

Resource URL¶

https://ads-api.twitter.com/4/accounts/:account_id/line_items

Parameters¶

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
campaign_id required	The identifier for the campaign to create the line item under. Type: string Example: `8slvg`
objective required	The campaign objective for this line item. Type: enum Possible values: `APP_ENGAGEMENTS`, `APP_INSTALLS`, `AWARENESS`, `FOLLOWERS`, `TWEET_ENGAGEMENTS`, `VIDEO_VIEWS`, `VIDEO_VIEWS_PREROLL`, `WEBSITE_CLICKS`
placements required	The placement location(s) for this line item to display in. Specify a comma-separated list of placement values. Type: enum Possible values: `ALL_ON_TWITTER`, `PUBLISHER_NETWORK`, `TWITTER_PROFILE`, `TWITTER_SEARCH`, `TWITTER_TIMELINE`
product_type required	The type of promoted product that this line item will contain. Type: enum Possible values: `MEDIA`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEETS`
advertiser_domain sometimes required	The website domain for this advertiser, without the protocol specification. Note: Required when the line item’s placement is set to `PUBLISHER_NETWORK`. Type: string Example: `twitter.com`
bid_amount_local_micro sometimes required	The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. Note: Required if `bid_type` is set to either `MAX` or `TARGET` or if `automatically_set_bid` is `false`. Note: Only values greater than zero are accepted. Type: long Example: `5500000`
categories sometimes required	The relevant IAB categories for this advertiser. See GET iab_categories. Note: Required when the line item’s placement is set to `PUBLISHER_NETWORK`. Type: string Example: `IAB3-1`
advertiser_user_id optional	The Twitter user identifier for the handle promoting a `VIDEO_VIEWS_PREROLL` ad. Use of this parameter is restricted to whitelisted advertisers only. Type: long Example: `312226591`
automatically_select_bid optional	Automatically optimize bidding based on daily budget and campaign flight dates. If set to `true`, `bid_amount_local_micro` is not required and should not be set and the `bid_type` will be set to `AUTO`. Note: Cannot be set in the same request as `bid_type`. Type: boolean Possible values: `true`, `false`
bid_type optional	The bidding mechanism. `AUTO` automatically optimizes bidding based on daily budget and campaign flight dates. `MAX` sets the maximum allowable bid and is not available when the objective is set to `AWARENESS` or `FOLLOWERS`. `TARGET` attempts to make daily bid averages within 20% of the specified `bid_amount_local_micro` and is available when the objective is set to `AWARENESS`, `FOLLOWERS`, OR `WEBSITE_CLICKS`. Note: If set to `AUTO`, `bid_amount_local_micro` will be ignored. Note: Cannot be set in the same request as `automatically_set_bid`. Note: Default based on objective. Type: enum Possible values: `AUTO`, `MAX`, `TARGET`
bid_unit optional	The bid unit for this line item. This setting is available for line items using the `APP_INSTALLS` or `VIDEO_VIEWS` objectives. Note: For other objectives, the bid unit is automatically set. Type: enum Possible values: `APP_CLICK`, `APP_INSTALL`, `VIEW`, `VIEW_3S_100PCT`
charge_by optional	The unit to charge this line item by. This setting is only available for line items using the `APP_INSTALLS` objective, where `charge_by` defaults to `APP_CLICK`. Note: For other objectives, `charge_by` is automatically set and defaults to the line item’s bid unit. Type: enum Possible values: `APP_CLICK`, `APP_INSTALL`
end_time optional	The time, expressed in ISO 8601, that the line item will stop serving. Type: string Example: `2017-10-05T00:00:00Z`
entity_status optional	The line item status. Type: enum Default: `ACTIVE` Possible values: `ACTIVE`, `DRAFT`, `PAUSED`
include_sentiment optional	Allows the line item to be targeted to Tweets with positive or with both positive and negative sentiment. Note: Only valid for the `PROMOTED_TWEETS` product type and with either placements of `ALL_ON_TWITTER` or `TWITTER_TIMELINES`. Type: enum Default: `POSITIVE_ONLY` Possible values: `ALL`, `POSITIVE_ONLY`
lookalike_expansion optional	Used to expand the reach of campaigns by targeting users similar to those already targeted. Use of this parameter is restricted to whitelisted advertisers only. Note: By default, no expansion will be applied. Type: enum Possible values: `BROAD`, `DEFINED`, `EXPANDED`
name optional	The name for the line item. Type: string Example: `demo`
optimization optional	The optimization setting to use with this line item. Type: enum Default: `DEFAULT` Possible values: `DEFAULT`, `ENGAGEMENTS`, `WEBSITE_CONVERSIONS`
primary_web_event_tag optional	The identifier of the primary web event tag. Allows more accurate tracking of engagements for the campaign pertaining to this line item. Type: string Example: `nvo4z`
start_time optional	The time, expressed in ISO 8601, that the line item will begin serving. Type: string Example: `2017-07-05T00:00:00Z`
total_budget_amount_local_micro optional	The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: `37500000`
tracking_tags optional	The tracking partner enum and the tracking tag url provided by the tracking partner, separated by a dash. Type: string Example: `DOUBLE_CLICK-https://partner_provided_url`

Example Request¶

POST https://ads-api.twitter.com/4/accounts/18ce54d4x5t/line_items?campaign_id=8slvg&objective=TWEET_ENGAGEMENTS&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&bid_amount_local_micro=3210000&entity_status=PAUSED

Example Response¶

{
  "data": {
    "bid_type": "MAX",
    "advertiser_user_id": 756201191646691328,
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "start_time": null,
    "bid_amount_local_micro": 3210000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "target_cpa_local_micro": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "end_time": null,
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "TWEET_ENGAGEMENTS",
    "id": "95lya",
    "entity_status": "PAUSED",
    "account_id": "18ce54d4x5t",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2017-06-23T01:59:22Z",
    "tracking_tags": [],
    "updated_at": "2017-06-23T01:59:22Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "8slvg",
    "creative_source": "MANUAL",
    "deleted": false
  },
  "request": {
    "params": {
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 3210000,
      "product_type": "PROMOTED_TWEETS",
      "objective": "TWEET_ENGAGEMENTS",
      "entity_status": "PAUSED",
      "account_id": "18ce54d4x5t",
      "campaign_id": "8slvg"
    }
  }
}

POST batch/accounts/:account_id/line_items¶

Allows the batch creation of new line items with a single request.

Batch Requests

The current maximum batch size is 20.
All parameters are sent in the request body and a Content-Type of application/json is required.
Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.

Batch Responses

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

Batch Errors

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

Resource URL¶

https://ads-api.twitter.com/4/batch/accounts/:account_id/line_items

Parameters¶

Name Description

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

operation_type

required

The per item operation type being performed.

Type: enum

Possible values: Create, Delete, Update

params

required

A JSON object containing all the parameters for the line item objects. For a list of required and optional line item parameters, see here.

Example Request¶

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

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

Example Response¶

{
  "data": [
    {
      "bid_type": "MAX",
      "advertiser_user_id": 756201191646691328,
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "start_time": null,
      "bid_amount_local_micro": 3210000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "target_cpa_local_micro": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "end_time": null,
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": null,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "9cqi0",
      "entity_status": "PAUSED",
      "account_id": "18ce54d4x5t",
      "optimization": "DEFAULT",
      "categories": [],
      "currency": "USD",
      "created_at": "2017-07-07T17:42:20Z",
      "tracking_tags": [],
      "updated_at": "2017-07-07T17:42:20Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "8yn7m",
      "creative_source": "MANUAL",
      "deleted": false
    }
  ],
  "request": [
    {
      "params": {
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "bid_amount_local_micro": 3210000,
        "product_type": "PROMOTED_TWEETS",
        "objective": "TWEET_ENGAGEMENTS",
        "entity_status": "PAUSED",
        "account_id": "18ce54d4x5t",
        "campaign_id": "8yn7m"
      },
      "operation_type": "Create"
    }
  ]
}

PUT accounts/:account_id/line_items/:line_item_id¶

Update the specified line item associated with the current account.

Resource URL¶

https://ads-api.twitter.com/4/accounts/:account_id/line_items/:line_item_id

Parameters¶

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
line_item_id required	A reference to the line item you are operating with in the request. Type: string Example: `8v7jo`
advertiser_domain optional	The website domain for this advertiser, without the protocol specification. Note: Required when the line item’s placement is set to `PUBLISHER_NETWORK`. Type: string Example: `twitter.com`
advertiser_user_id optional	The Twitter user identifier for the handle promoting a `VIDEO_VIEWS_PREROLL` ad. Use of this parameter is restricted to whitelisted advertisers only. Type: long Example: `312226591`
automatically_select_bid optional	Automatically optimize bidding based on daily budget and campaign flight dates. If set to `true`, `bid_amount_local_micro` is not required and should not be set and the `bid_type` will be set to `AUTO`. Note: Cannot be set in the same request as `bid_type`. Type: boolean Possible values: `true`, `false`
bid_amount_local_micro optional	The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. Note: Required if `bid_type` is set to either `MAX` or `TARGET` or if `automatically_set_bid` is `false`. Note: Only values greater than zero are accepted. Type: long Example: `140000`
bid_type optional	The bidding mechanism. `AUTO` automatically optimizes bidding based on daily budget and campaign flight dates. `MAX` sets the maximum allowable bid and is not available when the objective is set to `AWARENESS` or `FOLLOWERS`. `TARGET` attempts to make daily bid averages within 20% of the specified `bid_amount_local_micro` and is available when the objective is set to `AWARENESS` or `WEBSITE_CLICKS`. Note: If set to `AUTO`, `bid_amount_local_micro` will be ignored. Note: Cannot be set in the same request as `automatically_set_bid`. Note: Default based on objective. Type: enum Possible values: `AUTO`, `MAX`, `TARGET`
categories optional	The relevant IAB categories for this advertiser. See GET iab_categories. Note: Required when the line item’s placement is set to `PUBLISHER_NETWORK`. Type: string Example: `IAB3-1`
end_time optional	The time, expressed in ISO 8601, that the line item will stop serving. Type: string Example: `2017-10-05T00:00:00Z`
entity_status optional	The line item status. Type: enum Possible values: `ACTIVE`, `PAUSED`
include_sentiment optional	Allows the line item to be targeted to Tweets with positive or with both positive and negative sentiment. Note: Only valid for the `PROMOTED_TWEETS` product type and with either placements of `ALL_ON_TWITTER` or `TWITTER_TIMELINES`. Type: enum Possible values: `ALL`, `POSITIVE_ONLY`
lookalike_expansion optional	Used to expand the reach of campaigns by targeting users similar to those already targeted. Use of this parameter is restricted to whitelisted advertisers only. Type: enum Possible values: `BROAD`, `DEFINED`, `EXPANDED`
name optional	The name for the line item. Type: string Example: `demo`
optimization optional	The optimization setting to use with this line item. Type: enum Possible values: `DEFAULT`, `ENGAGEMENTS`, `WEBSITE_CONVERSIONS`
start_time optional	The time, expressed in ISO 8601, that the line item will begin serving. Type: string Example: `2017-07-05T00:00:00Z`
total_budget_amount_local_micro optional	The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000. Type: long Example: `37500000`
tracking_tags optional	The tracking partner enum and the tracking tag url provided by the tracking partner, separated by a dash. Type: string Example: `DOUBLE_CLICK-https://partner_provided_url`

Example Request¶

PUT https://ads-api.twitter.com/4/accounts/18ce54d4x5t/line_items/8v7jo?bid_amount_local_micro=140000

Example Response¶

{
  "data": {
    "bid_type": "MAX",
    "advertiser_user_id": 756201191646691328,
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "start_time": null,
    "bid_amount_local_micro": 140000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "target_cpa_local_micro": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "end_time": null,
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "TWEET_ENGAGEMENTS",
    "id": "8v7jo",
    "entity_status": "ACTIVE",
    "account_id": "18ce54d4x5t",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2017-05-27T08:04:00Z",
    "tracking_tags": [],
    "updated_at": "2017-07-04T22:01:28Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "8gdx6",
    "creative_source": "MANUAL",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "8v7jo",
      "bid_amount_local_micro": 140000,
      "account_id": "18ce54d4x5t"
    }
  }
}

DELETE accounts/:account_id/line_items/:line_item_id¶

Delete the specified line item belonging to the current account.

Note: Deleting a line item is not reversible and subsequent attempts to delete the resource will return HTTP 404.

Resource URL¶

https://ads-api.twitter.com/4/accounts/:account_id/line_items/:line_item_id

Parameters¶

Name Description

account_id

required

Type: string

Example: 18ce54d4x5t

line_item_id

required

A reference to the line item you are operating with in the request.

Type: string

Exampple: 9f2ix

Example Request¶

DELETE https://ads-api.twitter.com/4/accounts/18ce54d4x5t/line_items/9f2ix

Example Response¶

{
  "data": {
    "bid_type": "MAX",
    "advertiser_user_id": 756201191646691328,
    "name": "Untitled",
    "placements": [],
    "start_time": null,
    "bid_amount_local_micro": 100000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "target_cpa_local_micro": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "end_time": "2017-07-21T00:00:00Z",
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "TWEET_ENGAGEMENTS",
    "id": "9f2ix",
    "entity_status": "ACTIVE",
    "account_id": "18ce54d4x5t",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2017-07-14T00:01:50Z",
    "tracking_tags": [],
    "updated_at": "2017-08-09T07:41:08Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "90r8n",
    "creative_source": "MANUAL",
    "deleted": true
  },
  "request": {
    "params": {
      "line_item_id": "9f2ix",
      "account_id": "18ce54d4x5t"
    }
  }
}

Campaign Management

Line Items¶

GET accounts/:account_id/line_items¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

GET accounts/:account_id/line_items/:line_item_id¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

POST accounts/:account_id/line_items¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

POST batch/accounts/:account_id/line_items¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

PUT accounts/:account_id/line_items/:line_item_id¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

DELETE accounts/:account_id/line_items/:line_item_id¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

Was this document helpful?

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.