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

Parameters

Name Description
account_id
required

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

Type: string

Example: 18ce54d4x5t

campaign_ids
optional

Scope the response to just the line items under specific campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 8gdx6

count
optional

Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional

Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow

funding_instrument_ids
optional

Scope the response to just the line items under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: lygyi

line_item_ids
optional

Scope the response to just the desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 8v7jo

q
optional

An optional query to scope resource by name.

Type: string

Min, Max length: 1, 255
sort_by
optional

Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc

with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_draft
optional

Include draft campaigns results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional

Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "line_item_ids": [
        "8v7jo"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "bid_strategy": "MAX",
      "advertiser_user_id": 756201191646691328,
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "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": null,
      "duration_in_days": 1,
      "total_budget_amount_local_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "8v7jo",
      "entity_status": "ACTIVE",
      "goal": "ENGAGEMENT",
      "frequency_cap": 5,
      "categories": [],
      "currency": "USD",
      "created_at": "2017-05-27T08:04:00Z",
      "updated_at": "2017-05-27T08:06:25Z",
      "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/10/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/10/accounts/18ce54d4x5t/line_items/8v7jo

Example Response

{
  "request": {
    "params": {
      "line_item_id": "8v7jo",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "bid_strategy": "MAX",
    "advertiser_user_id": 756201191646691328,
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "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": null,
    "duration_in_days": 1,
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "8v7jo",
    "entity_status": "ACTIVE",
    "goal": "ENGAGEMENT",
    "frequency_cap": 5,
    "categories": [],
    "currency": "USD",
    "created_at": "2017-05-27T08:04:00Z",
    "updated_at": "2017-05-27T08:06:25Z",
    "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.

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

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

Resource URL

https://ads-api.twitter.com/10/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, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKS

placements
required

The placement location(s) for this line item to display in. Specify a comma-separated list of placement values.

Type: enum

Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK, TAP_BANNER, TAP_FULL, TAP_FULL_LANDSCAPE, TAP_NATIVE, TAP_MRECT, TWITTER_PROFILE, TWITTER_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

android_app_store_identifier
sometimes required

The Google App Store identifier for promoted applications.

Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier -- either android_app_store_identifier or ios_app_store_identifier.

Type: string

Example: com.twitter.android

bid_amount_local_micro
sometimes required

The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000.

Note: Required if bid_strategy is set to either MAX or TARGET

Note: Only values greater than zero are accepted.

Type: long

Example: 5500000

categories
sometimes required

The relevant IAB categories for this advertiser. See GET iab_categories.

Note: Required when the line item's placement is set to PUBLISHER_NETWORK.

Type: string

Example: IAB3-1

ios_app_store_identifier
sometimes required

The numeric portion of the Apple App Store identifier for promoted applications.

Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier -- either android_app_store_identifier or ios_app_store_identifier.

Type: string

Example: 333903271

primary_web_event_tag
sometimes required

The identifier of the primary web event tag. Allows more accurate tracking of engagements for the campaign pertaining to this line item.

Note: Required when the line item's goal is set to WEBSITE_CONVERSIONS.

Type: string

Example: nvo4z

advertiser_user_id
optional

The Twitter user identifier for the handle promoting a PREROLL_VIEWS ad. Only certain client applications may use this parameter.

Type: long

Example: 312226591

audience_expansion
optional

Used to expand the reach of campaigns by targeting users similar to those already targeted.

Note: By default, no expansion will be applied.

Type: enum

Possible values: BROAD, DEFINED, EXPANDED

bid_strategy
optional

The bidding mechanism.

AUTO automatically optimizes bidding based on daily budget and campaign flight dates.

MAX sets the maximum allowable bid and is not available when the objective is set to REACH or FOLLOWERS.

TARGET attempts to make daily bid averages within 20% of the specified bid_amount_local_micro and is available when the objective is set to REACH, FOLLOWERS, OR WEBSITE_CLICKS.

Note: If set to AUTO, bid_amount_local_micro will be ignored.

Note: Default based on objective.

Type: enum

Possible values: AUTO, MAX, TARGET

duration_in_days
optional

The time period within which the frequency_cap is achieved.

Type: int

Possible values: 1, 7, 30

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
frequency_cap
optional

The maximum number of times an ad could be delivered to a user.

Note: Only supported for REACH, ENGAGEMENTS, VIDEO_VIEWS, and PREROLL_VIEWS objectives.

Type: int

Example: 5

goal
optional

The optimization setting to use with this line item. The APP_CLICKS and APP_INSTALLS options are available for APP_INSTALL and APP_ENGAGEMENTS and may require using a supported MACT partner.

Note: Default based on objective.

Type: enum

Possible values: APP_CLICKS, APP_INSTALLS, ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
name
optional

The name for the line item.

Type: string

Example: demo

Min, Max length: 1, 255
pay_by
optional

The unit to charge this line item by. This setting can only be modified for line items using the APP_INSTALLS objective.

Note: The default pay_by is automatically set based upon the campaign objective and line item's bid unit.

Type: enum

Possible values: APP_CLICK

start_time
optional

The time, expressed in ISO 8601, that the line item will begin serving.

Type: string

Example: 2017-07-05T00:00:00Z

total_budget_amount_local_micro
optional

The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000.

Type: long

Example: 37500000

Example Request

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

Example Response

{
  "data": {
    "bid_strategy": "MAX",
    "advertiser_user_id": 756201191646691328,
    "name": "Untitled",
    "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,
    "pay_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "end_time": null,
    "duration_in_days": null,
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "frequency_cap": null,
    "id": "95lya",
    "entity_status": "PAUSED",
    "goal": "ENGAGEMENT",
    "categories": [],
    "currency": "USD",
    "created_at": "2017-06-23T01:59:22Z",
    "updated_at": "2017-06-23T01:59:22Z",
    "campaign_id": "8slvg",
    "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": "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 40.
  • All parameters are sent in the request body and a Content-Type of application/json is required.
  • Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.

Batch Responses

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

Batch Errors

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

Resource URL

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

Parameters

Name Description
operation_type
required

The per item operation type being performed.

Type: enum

Possible values: Create, Delete, Update

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

Example Request

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

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

Example Response

{
  "data": [
    {
      "bid_strategy": "MAX",
      "advertiser_user_id": 756201191646691328,
      "name": "Untitled",
      "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,
      "pay_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "end_time": null,
      "total_budget_amount_local_micro": null,
      "objective": "ENGAGEMENTS",
      "id": "9cqi0",
      "entity_status": "PAUSED",
      "goal": "ENGAGEMENT",
      "categories": [],
      "currency": "USD",
      "created_at": "2017-07-07T17:42:20Z",
      "updated_at": "2017-07-07T17:42:20Z",
      "campaign_id": "8yn7m",
      "creative_source": "MANUAL",
      "deleted": false
    }
  ],
  "request": [
    {
      "params": {
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "bid_amount_local_micro": 3210000,
        "product_type": "PROMOTED_TWEETS",
        "objective": "ENGAGEMENTS",
        "entity_status": "PAUSED",
        "account_id": "18ce54d4x5t",
        "campaign_id": "8yn7m"
      },
      "operation_type": "Create"
    }
  ]
}

PUT accounts/:account_id/line_items/:line_item_id

Update the specified line item associated with the current account.

Resource URL

https://ads-api.twitter.com/10/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 PREROLL_VIEWS ad. Only certain client applications may use this parameter.

Type: long

Example: 312226591

android_app_store_identifier
optional

The Google App Store identifier for the promoted application.

Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier -- either android_app_store_identifier or ios_app_store_identifier.

Type: string

Example: com.twitter.android

audience_expansion
optional

Used to expand the reach of campaigns by targeting users similar to those already targeted.

Type: enum

Possible values: BROAD, DEFINED, EXPANDED

bid_amount_local_micro
optional

The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000.

Note: Required if bid_strategy is set to either MAX or TARGET

Note: Only values greater than zero are accepted.

Type: long

Example: 140000

bid_strategy
optional

The bidding mechanism.

AUTO automatically optimizes bidding based on daily budget and campaign flight dates.

MAX sets the maximum allowable bid and is not available when the objective is set to REACH or FOLLOWERS.

TARGET attempts to make daily bid averages within 20% of the specified bid_amount_local_micro and is available when the objective is set to REACH or WEBSITE_CLICKS.

Note: If set to AUTO, bid_amount_local_micro will be ignored.

Note: Default based on objective.

Type: enum

Possible values: AUTO, MAX, TARGET

categories
optional

The relevant IAB categories for this advertiser. See GET iab_categories.

Note: Required when the line item's placement is set to PUBLISHER_NETWORK.

Type: string

Example: IAB3-1

duration_in_days
optional

The time period within which the frequency_cap is achieved.

Type: int

Possible values: 1, 7, 30

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

frequency_cap
optional

The maximum number of times an ad could be delivered to a user.

Note: Only supported for REACH, ENGAGEMENTS, VIDEO_VIEWS, and PREROLL_VIEWS objectives.

Type: int

Example: 5

goal
optional

The optimization setting to use with this line item. The APP_CLICKS and APP_INSTALLS options are available for APP_INSTALL and APP_ENGAGEMENTS and may require using a supported MACT partner.

Note: Default based on objective.

Type: enum

Possible values: APP_CLICKS, APP_INSTALLS, ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
ios_app_store_identifier
optional

The numeric portion of the Apple App Store identifier for promoted applications.

Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier -- either android_app_store_identifier or ios_app_store_identifier.

Type: string

Example: 333903271

name
optional

The name for the line item.

Type: string

Example: demo

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

Example Request

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

Example Response

{
  "data": {
    "bid_strategy": "MAX",
    "advertiser_user_id": 756201191646691328,
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "start_time": null,
    "bid_amount_local_micro": 140000,
    "advertiser_domain": null,
    "target_cpa_local_micro": null,
    "primary_web_event_tag": null,
    "pay_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "duration_in_days": 1,
    "end_time": null,
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "8v7jo",
    "entity_status": "ACTIVE",
    "goal": "ENGAGEMENT",
    "frequency_cap": 5,
    "categories": [],
    "currency": "USD",
    "created_at": "2017-05-27T08:04:00Z",
    "updated_at": "2017-07-04T22:01:28Z",
    "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.

Note: When a line item is deleted, its child promoted_tweets are only returned in the GET accounts/:account_id/promoted_tweets and GET accounts/:account_id/promoted_tweets/:promoted_tweet_id endpoints if with_deleted=true is specified in the request. These promoted_tweets are not actually deleted, though ("deleted": false in the response). We do not cascade deletes.

Resource URL

https://ads-api.twitter.com/10/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/10/accounts/18ce54d4x5t/line_items/9f2ix

Example Response

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

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.