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.x.com/6/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 https://ads-api.x.com/6/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
        ]
      }
    }
  ]
}