What’s New

To stay current with changes, updates and new features in the Gemini API, you’ll want to read this section. The What’s New is updated on a weekly cadence for Gemini API partners and developers.

Each month the Gemini Product Bulletin summarizes the latest updates and changes based on input from the Gemini team. Be sure to read the Bulletins to retrieve information that may impact your product development.


Tune into the May Product Bulletin podcast.

Release Notes

Gemini Release Notes are now archived in Resources and available if you wish to review past changes.

Gemini v3 API

The new v3 API has been released as of 25 July 2017. This release provides partners and developers with the following features and capabilities:

  • Support for Upgraded URLs (UUs), which enable you to better define and control the landing page and tracking of your URLs. For more information on Upgraded URLs (UUs) in v3, refer to Upgraded URLs.

  • Greater API object stability, as well as improved management of API changes, building on the enhancements in v2 Gemini API.

  • Support for Site X Device Targeting with new available targeting attributes. For more information, refer to Targeting Attributes. Note that Site X Device targeting is also supported in the v2 Gemini API.

  • New reporting cubes available for querying at the ad group level:

    • site_performance_stats for use when querying for native ads campaign data.
    • campaign_bid_performance_stats for use when evaluating group-level bid modifiers.

For more information, refer to Cubes.

  • New reporting dimensions available for querying at the advertiser, ad, campaign, ad group and keyword levels. For more information, refer to Dimensions.
  • Postman examples added for Upgraded URLs (v3) and Bid by Site (v2). For more information, refer to Postman API Toolkit.
  • Additional bug and error fixes for improved performance and stability.


Developers are encouraged to migrate to the v3 Gemini API in order to maintain access to the latest features and functionality. Please note that new features are only added to the current version.

Gemini v2 API

The v2 API includes the following changes:

  • Gemini v2 API has been released. Starting on 1 June 2016, Yahoo Gemini will migrate the programmatic Gemini API from v1 to v2; the current version of the Gemini API will be v2. Be sure to read the sections on Versioning and API v1 Deprecation, plus the FAQs for details.
  • Developers are encouraged to migrate to the v2 Gemini API in order to maintain access to the latest features and functionality. Please note that new features are only added to the current version. In the event of a special situation that would require a fundamental change across all versions, a migration path will be provided. For any migration, you will have at least a 90-day window to migrate and integrate your app.


The Gemini v1 API will be supported for 90 days beyond the June 1, 2016 deprecation date. After that date, starting on September 1, 2016, the Gemini v1 API will be available for one year. After that time, it will be relegated to End of Life (EOL) status.

  • With the v2 release, new v2 Shared Set Libraries have been added that enable you to create, populate and associate shared sets to your campaigns and ad groups. New v2 Shared Site Link has been added with methods for creating, updating and retrieving shared sitelinks.


In the v2 API, only one parentId parameter is allowed to be passed in as a query parameter for all filtered list GET calls. This change will have impact when you filter lists of GET calls on ad, ad group, campaign, ad extensions, keyword, targeting, shared sitelinks, and created, populated and associated shared set calls. Refer to each of the relevant sections in the documentation for details.

v2 Data Model

The v2 Gemini API introduces a new data model with new entities, as shown in the diagram below. The v2 data model illustrates how shared sets and the new shared site link objects work and connect.

v2 api gemini data model

For more information, see the v2 Shared Set Libraries and the v2 Shared Site Link sections.

Other New Features, Changes & Enhancements

  • New call_extension_stats cube has been added to Reporting. Use this cube to get detailed information about conversions on click 2 call ad extensions at the account, campaign and adgroup levels. For more information, see call_extension_stats.
  • Note the following: Any changes to either the landing urls or the text attributes of the following entities – Ad, Keywords and Sitelinks – will result in a state transition to ON_HOLD for the purposes of editorial review. Note that our SLA is 24 hours; however, in practice, most ads are re-activated in 1 to 2 hours. Please plan your edits and sync logic, accordingly.
  • New, detailed explanation of Steps to follow before you begin OAuth 2.0 authentication. If you’re new to the Gemini API, you should read the section and follow the steps listed. Note also in the section on OAuth refresh tokens that access tokens will expire after 60 minutes.
  • New Keyword status and editorialStatus fields added in v2. Also, new Ad status and editorialStatus fields added in v2.
  • New Bulk schema upload and download changes in v2, providing partners and developers with a unified format for bulk operations and data representation. To consolidate all targeting attributes in bulk files to a single, unified standard, as well as expose targeting attribute entity IDs for all objects, the v2 Gemini AP includes the changes described in Bulk schema upload and download.
  • New, re-architected Gemini API Table of Contents for easier navigation and retrieval of documentation topics and information. With the introduction of v2, we’ve organized and consolidated much of the technical content, so that each topic folder contains the specific information you need when coding and integrating your apps. If you’ve bookmarked topics in the v1 API, you may find some of those links broken; you’ll need to bookmark new links that are relevant to your development efforts.

Release Notes - Archived

The Release Notes section is now an Archive of notes in Resources, dating back to the initial release of the v1 Gemini API. Explore these if you need to track changes, updates and enhancements to the API over time.


You may wish to check out these additional, external resources dedicated to working with Gemini and the Gemini API: