Ads API Version 1

Version 1 of the Ads API launched March 31, 2016. Version 0 of the Ads API will be supported until October 31, 2016.

Changes in version 1:

  • Versioning support
  • CUSTOM objective is no longer supported
  • Batch endpoints are now generally available
  • Reach estimate changes:
  • To provide better reach estimation, the endpoint is now budget aware. The following parameters are now required:
    • [new] campaign_daily_budget_amount_local_micro
    • currency
    • bid
    • objective
  • The response object has changed, and now returns ranges for response values.
  • infinite_count has been renamed infinite_bid_count to avoid confusion on its purpose
  • In addition to count and infinite_bid_count, these new data points will now be returned:
    • impressions
    • engagements
    • estimated_daily_spend_local_micro
  • Data type change for tailored audiences
  • The data_type for Tailored Audiences has been changed from tailored_audiences to tailored_audience in all of our resposnes.
  • Shared Tailored Audiences are now available as an API-only beta. Shared tailored audiences allow for a single audience to be used across multiple ads accounts. Use the POST /1/accounts/:account_id/tailored_audiences/:id/permissions (and related) endpoint to manage permissions of a tailored audience you would like to share across ads accounts.
  • Significant improvements in how you collect performance analytics for advertiser accounts:
  • To align with our best practices, we will now only allow data to be pulled for up to 7 days of data for the synchronous stats endpoints.
  • To simplify pulling metrics, we have replaced the metrics parameter with a new metric_groups parameter. Developers simply must request which groups of metrics they would like returned for a given request.
    • Any request for metrics that are not appropriate for a given entity will be excluded from the response and represented as null values. These metrics will not count against your analytics cost limit.
  • The response has been significantly simplified, and will now align more closely with how metrics are exposed in our UI.
    • Previously we exposed a separate metric for each placement location (Promoted Tweets in Search, Promoted Tweets in Timelines, Promoted Tweets in Profiles & Tweet Details, Twitter Audience Platform). We will now return a standardized set of metrics for each (instead of promoted_tweet_timeline_impressions, promoted_tweet_search_impressions, promoted_tweets_profile_impressions, promoted_tweets_tpn_impressions), these will now be exposed when requested in one of the following categories as a single metric, impressions (this applies to all metrics):
    • ALL_ON_TWITTER
    • PUBLISHER_NETWORK
    • When you make a request you’ll get a single impressions metric to make matching values in our UI simplier.
    • You must make two queries to get both ALL_ON_TWITTER and PUBLISHER_NETWORK data, as these cannot be combined.
  • Asynchronous stats endpoints are now available, based on feedback from our developers!
    • A new set of endpoints to request stats asynchronously, for data you don’t need immediately or for historic data pulls.
    • Queue a stats job using a new single endpoint. We’ll pull the data you have requested as resources allow.
    • You can query a job status endpoint to determine if the data is available.
    • Once the data is available, we’ll provide a pick-up ID for you to download the JSON response, which will mirror the response from the synchronous endpoint.
    • Query up to 90 days of data on up to 20 entities in a single job.
  • Take a look at our analytics v1 migration guide, which includes mapping of v0 metrics to v1 metrics
  • Sandbox improvements * You may now create multiple test ads accounts in the Sandbox environment. * You may now create multiple funding instruments for a test ads account in the Sandbox environment only. This allows you to test on all of our funding instrument types. Previously only a CREDIT_CARD funding source was available to test with. * Want to test a beta feature? You can now toggle features on/off for an account in the Sandbox environment to accommodate your testing needs.