Ads API Version 1.0

Version 1.0 of the Ads API launched March 31, 2016. Version 0.0 of the Ads API will be supported until June 30, 2016.

Changes in version 1.0:

• 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, including at different service levels.
  • 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.