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/2/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 line items under draft campaigns.

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/2/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/2/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/2/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/2/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, LIVE_TV_EVENT, 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 developers 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 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
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/2/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/2/batch/accounts/:account_id/line_items

Parameters

Name Description
operation_type
required

The per item operation type being performed.

Type: enum

Possible values: Create, Delete

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/2/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/2/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 developers 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

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/2/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/2/accounts/:account_id/line_items/:line_item_id

Parameters

Name Description
account_id
required

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

Type: string

Example: 18ce54d4x5t

line_item_id
required

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

Type: string

Exampple: 9f2ix

Example Request

DELETE https://ads-api.twitter.com/2/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"
    }
  }
}