Active Entities
active-entities

Active Entities

GET stats/accounts/:account_id/active_entities

Retrieve details about which entities' analytics metrics have changed in a given time period.

This endpoint should be used in conjunction with our analytics endpoints. The results of this endpoint indicate which ads entities to request analytics for. See our Active Entities Guide for usage guidelines.

Change events are available in hourly buckets.

  • The start_time and end_time values specify which hourly buckets to query.
  • The returned data array will include an object for every entity that should be included in subsequent analytics requests.
  • IMPORTANT: The dates that should be specified in subsequent analytics requests should be determined based on the activity_start_time and activity_end_time values.
    • These values represent the time ranges that the stored change events apply to. This is returned per entity.

Note: A maximum time range (end_time - start_time) of 90 days is allowed.

Resource URL

https://ads-api.x.com/12/stats/accounts/:account_id/active_entities

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: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET

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

campaign_ids
optional

Scope the response to just entities associated with desired campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Note: Exclusive with funding_instrument_ids and line_item_ids.

Type: string

Example: 8wku2

funding_instrument_ids
optional

Scope the response to just entities associated with desired funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Note: Exclusive with campaign_ids and line_item_ids.

Type: string

Example: lygyi

line_item_ids
optional

Scope the response to just entities associated with desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Note: Exclusive with campaign_ids and line_item_ids.

Type: string

Example: 8v7jo

Example Request

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-02-28&end_time=2019-03-01

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "entity": "PROMOTED_TWEET",
      "start_time": "2019-02-28T08:00:00Z",
      "end_time": "2019-03-01T08:00:00Z"
    }
  },
  "data": [
    {
      "entity_id": "2mvb28",
      "activity_start_time": "2019-02-28T01:30:07Z",
      "activity_end_time": "2019-03-01T07:42:55Z",
      "placements": [
        "ALL_ON_TWITTER"
      ]
    },
    {
      "entity_id": "2mvb29",
      "activity_start_time": "2019-02-27T11:30:07Z",
      "activity_end_time": "2019-03-01T07:42:50Z",
      "placements": [
        "ALL_ON_TWITTER",
        "PUBLISHER_NETWORK"
      ]
    },
    {
      "entity_id": "2mvfan",
      "activity_start_time": "2019-02-27T09:00:05Z",
      "activity_end_time": "2019-03-01T06:06:36Z",
      "placements": [
        "PUBLISHER_NETWORK"
      ]
    },
    {
      "entity_id": "2n17dx",
      "activity_start_time": "2019-02-28T02:02:26Z",
      "activity_end_time": "2019-03-01T07:52:44Z",
      "placements": [
        "ALL_ON_TWITTER",
        "PUBLISHER_NETWORK"
      ]
    }
  ]
}