Auction Insights

GET accounts/:account_id/auction_insights

Retrieve auction insights for specific line items belonging to the current account.

Use the granularity parameter with the DAY value to retrieve data in a time-series format. For summary results, use granularity=TOTAL.

  • The Auction Insights API is only available to approved partners.
  • start_time and end_time values must correspond to midnight in the account's timezone, relative to UTC. Input values that omit the timestamp, such as 2012-07-06, will be automatically translated to the appropriate UTC value.
  • Insights are available 24 hours after the specified end_time.

Resource URL

https://ads-api.twitter.com/5/accounts/:account_id/auction_insights

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

end_time
required

The time, expressed in ISO 8601, that the campaign will end.

Type: string

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

granularity
required

Specifies the granularity of the data returned for the time range denoted by start_time and end_time. For instance, when set to HOUR, you will be presented with a datapoint for each hour between start_time and end_time. request.

Type: enum

Possible values: DAY, HOUR

line_item_ids
required

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

placement
required

Scopes the retrieved data to a particular placement.

Note: Only a single value accepted per request. For entities with both Twitter and Twitter Audience Platform placement, separate requests are required, one for each placement value.

Type: enum

Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK

start_time
required

The time, expressed in ISO 8601, that the campaign will begin.

Type: string

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

Example Request

GET http://ads-api.twitter.com/5/accounts/18ce54ayf0z/auction_insights?line_item_ids=65vb5&start_time=2016-10-13&end_time=2016-10-20&granularity=DAY&placement=ALL_ON_TWITTER

Example Response

{
  "request": {
    "params": {
      "start_time": "2016-10-13T04:00:00Z",
      "end_time": "2016-10-20T04:00:00Z",
      "line_item_ids": [
        "65vb5"
      ],
      "placement": "ALL_ON_TWITTER",
      "account_id": "18ce54ayf0z",
      "granularity": "DAY"
    }
  },
  "data_type": "auction_insights",
  "data": [
    {
      "id": "6h8ti",
      "metrics": {
        "auction_win_rate": [
          0,
          0.49200603213073075,
          0.46905638202455696,
          0.5052737952377945,
          0.48222824597204034,
          0.4375,
          0.4210509694940946,
          0
        ],
        "average_bid_local_micro": [
          0,
          2000000,
          2000000,
          2000000,
          2000000,
          2000000,
          2000000,
          0
        ],
        "average_price_local_micro": [
          0,
          1243410.8875739644,
          1579178.2220149254,
          1542697.1268817205,
          1572193.3380952382,
          1630722.08045977,
          1721891.4413580247,
          0
        ]
      }
    }
  ]
}