Synchronous Analytics
synchronous

Synchronous Analytics

GET stats/accounts/:account_id

Retrieve synchronous analytics for the current account. A maximum time range (end_time - start_time) of 7 days is allowed.

Resource URL

https://ads-api.twitter.com/12/stats/accounts/:account_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

end_time
required

Scopes the retrieved data to the specified end time, expressed in ISO 8601.

Note: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: 2017-05-26T07:00:00Z

entity
required

The entity type to retrieve data for.

Type: enum

Possible values: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE

entity_ids
required

The specific entities to retrieve data for. Specify a comma-separated list of entity IDs.

Note: Up to 20 entity IDs may be provided.

Type: string

Example: 8u94t

granularity
required

Specify how granular the retrieved data should be.

Type: enum

Possible values: DAY, HOUR, TOTAL

metric_groups
required

The specific metrics that should be returned. Specify a comma-separated list of metric groups. For more information see Metrics and Segmentation.

Note: MOBILE_CONVERSION data should be requested separately.

Type: enum

Possible values: BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION

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

Scopes the retrieved data to the specified start time, expressed in ISO 8601.

Note: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: 2017-05-19T07:00:00Z

Example Request

GET https://ads-api.twitter.com/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2017-05-19&end_time=2017-05-26&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT

Example Response

{
  "data_type": "stats",
  "time_series_length": 1,
  "data": [
    {
      "id": "8u94t",
      "id_data": [
        {
          "segment": null,
          "metrics": {
            "impressions": [
              1233
            ],
            "tweets_send": null,
            "qualified_impressions": null,
            "follows": null,
            "app_clicks": null,
            "retweets": null,
            "likes": [
              1
            ],
            "engagements": [
              58
            ],
            "clicks": [
              58
            ],
            "card_engagements": null,
            "poll_card_vote": null,
            "replies": null,
            "carousel_swipes": null
          }
        }
      ]
    }
  ],
  "request": {
    "params": {
      "start_time": "2017-05-19T07:00:00Z",
      "segmentation_type": null,
      "entity_ids": [
        "8u94t"
      ],
      "end_time": "2017-05-26T07:00:00Z",
      "country": null,
      "placement": "ALL_ON_TWITTER",
      "granularity": "TOTAL",
      "entity": "LINE_ITEM",
      "platform": null,
      "metric_groups": [
        "ENGAGEMENT"
      ]
    }
  }
}