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/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.twitter.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
        ]
      }
    }
  ]
}

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.