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/8/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/8/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"
      ]
    }
  }
}

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.