How to get historic performance data from ads API?

[addev]

Is there an optimal method to pull all historic performance data for all campaigns down to the tweet level? It looks like I need to pull all the campaigns and then get the performance data for each ads/tweet from each campaign individually. There has to be a better way since it’s so much easier on Facebook, where you put the date range and what parameters you want to retrieve. Is there a better way?

[juanshishido]

@addev: Thanks for your question. Please take a look at the Analytics Best Practices documentation.

In particular:

Do not repeatedly query for data that is older than 30 days. This data will not change and should be stored locally.

---

In terms of implementation, we suggest using the asynchronous analytics endpoint. Note that the maximum range for non-segmented queries is 90 days.

You can get a list of all Promoted Tweet IDs using:

$ twurl -H ads-api.twitter.com "/1/accounts/{account_id}/promoted_tweets"

With the list of ids—you can pass in multiple Promoted Tweet IDs—you can do the following to retrieve the analytics data (engagement data on Twitter at day granularity, in this example).

$ twurl -X POST -H ads-api.twitter.com "/1/stats/jobs/accounts/18ce54d4x5t?start_time=2016-08-01&end_time=2016-08-30&entity=PROMOTED_TWEET&entity_ids=10vvdm,10os5u,zz8yv,zhyo9&granularity=DAY&metric_groups=ENGAGEMENT&placement=ALL_ON_TWITTER" | jq
{
  "request": {
    "params": {
      "start_time": "2016-08-01T07:00:00Z",
      "entity_ids": [
        "10vvdm",
        "10os5u",
        "zz8yv",
        "zhyo9"
      ],
      "end_time": "2016-08-30T07:00:00Z",
      "placement": "ALL_ON_TWITTER",
      "granularity": "DAY",
      "entity": "PROMOTED_TWEET",
      "metric_groups": [
        "ENGAGEMENT"
      ]
    }
  },
  "data_type": "job",
  "data": {
    "start_time": "2016-08-01T07:00:00Z",
    "segmentation_type": null,
    "url": null,
    "id_str": "793172271397351424",
    "entity_ids": [
      "10vvdm",
      "10os5u",
      "zz8yv",
      "zhyo9"
    ],
    "end_time": "2016-08-30T07:00:00Z",
    "country": null,
    "placement": "ALL_ON_TWITTER",
    "id": 793172271397351400,
    "expires_at": null,
    "account_id": "18ce54d4x5t",
    "status": "PROCESSING",
    "granularity": "DAY",
    "entity": "PROMOTED_TWEET",
    "created_at": "2016-10-31T19:26:20Z",
    "platform": null,
    "metric_groups": [
      "ENGAGEMENT"
    ]
  }
}

Make note of the id_str attribute—you’ll use this to check on the status of the job:

$ twurl -H ads-api.twitter.com "/1/stats/jobs/accounts/18ce54d4x5t?job_ids=793172271397351424" | jq
{
  "request": {
    "params": {
      "job_ids": [
        793172271397351400
      ]
    }
  },
  "data_type": "job",
  "next_cursor": null,
  "data": [
    {
      "start_time": "2016-08-01T07:00:00Z",
      "segmentation_type": null,
      "url": {url},
      "id_str": "793172271397351424",
      "entity_ids": [
        "10vvdm",
        "10os5u",
        "zz8yv",
        "zhyo9"
      ],
      "end_time": "2016-08-30T07:00:00Z",
      "country": null,
      "placement": "ALL_ON_TWITTER",
      "id": 793172271397351400,
      "expires_at": "2016-11-02T19:26:23Z",
      "account_id": "18ce54d4x5t",
      "status": "SUCCESS",
      "granularity": "DAY",
      "entity": "PROMOTED_TWEET",
      "created_at": "2016-10-31T19:26:20Z",
      "platform": null,
      "metric_groups": [
        "ENGAGEMENT"
      ]
    }
  ]
}

When you see "status": "SUCCESS" you can download the data from what’s in the url attribute. It will be in the following format:

https://ton.twimg.com/advertiser-api-async-analytics/{some-long-string}.json.gz

Hope this helps!

[hector_borras]

Hi!

In order to retrieve historical data you can also split the timewindow in 90-days frames, and after, request it via asyncronous calls. Later on in your side you should organize and store that data.

Regards!