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