Product News

Supporting Edit Tweet functionality with new API metadata

  Peter Clowes, Sr. Software Engineer, @peterclowes

Aurelia Specker, Sr. Partner Engineer, @AureliaSpecker

  3 October 2022

  Peter Clowes, Sr. Software Engineer, @peterclowes

Aurelia Specker, Sr. Partner Engineer, @AureliaSpecker

3 October 2022

Today, we’re adding edited Tweet metadata to the Tweet object on the Twitter API v2 so that you can understand the edit history of public Tweets via API. 

As you may have seen, we recently announced that we were testing a new Edit Tweet feature, and today, we’re rolling out Edit Tweet for Twitter Blue members in New Zealand, Australia, and Canada. With this new feature, we understand the importance, for developers, of being able to retrieve this new Tweet data. Edited Tweet metadata is not an endpoint, but rather an addition of new fields and expansions to the Tweet object that is returned on all relevant v2 endpoints. Understanding edits to a Tweet is just as important as understanding replies, Retweets, engagement, and other metadata included in Tweets. 

Due to the incremental rollout plans for Edit Tweet, we do not expect a huge volume of edited Tweets initially. We hope this gives you time to understand how the edit data is represented in the API prior to Edit Tweet launching to more people on Twitter. 

How it works

Today’s solution updates all v2 endpoints that return a Tweet object so you can stay up to date with the edit history and current state of content on Twitter. The Twitter API v2 now returns the most recent version of edited Tweets, provides Tweet edit history, and additional edited Tweet metadata, all in a single API request. 

Specifically, two new fields are available via the Tweet object:

  • edit_history_tweet_ids returns an array of Tweet IDs corresponding to each version of a Tweet, beginning with the initial Tweet and ending with the most recent version of the Tweet. 

  • edit_controls tells a developer if a Tweet was eligible to be edited at the time of creation (Tweet edit eligibility requirements), provides the time the Tweet can be edited until (Tweets can only be edited for 30 minutes after the original Tweet was created), and gives the number of edits remaining (Tweets can be edited up to 5 times). 

Additionally, developers are able to request a Tweet expansion, edit_history_tweet_ids, that returns Tweet objects (copy, media, etc.) for a Tweet’s edit history, including the public metrics attributed to each Tweet version.  

For more information on new edited Tweet metadata, including sample responses, please refer to our documentation.

Support for legacy APIs (Standard, Premium, and Enterprise)

We are also adding new edited Tweet metadata to the Tweet objects returned by the v1.1 Standard, Premium, and Enterprise APIs. This new metadata provides an array of Tweet IDs for previous versions of a Tweet, indicates if a Tweet was ever edit eligible, provides a timestamp indicating when the 30-minute edit window will expire, and provides the number of edits remaining. 

However, the metadata returned for edited Tweets on our legacy APIs is less comprehensive than with our v2 solution. With v2, a developer is able to return a Tweet’s full edit history with a single request, including past Tweet versions via expansions, whereas with v1.1 a developer needs to make multiple API calls to return past Tweet versions and reproduce the same v2 functionality. 

Policy updates

Today's launch also includes updates to the Display Requirements to address expectations for displaying edited Tweets. This update specifies that when a Tweet is edited, you must display those edits as they occur on the Twitter platform and provide the Tweet’s edit history. Additionally, we expect developers to continue to comply with the Content Compliance policy, which stipulates that developers storing Twitter content keep their data up to date with the state of the content on Twitter, including for edited Tweets. For more, please read the policy.

To ensure you are able to stay compliant with these updates, we’re adding new compliance event types to existing compliance solutions.

What’s next?

Although the ability to edit Tweets is currently available only for Twitter Blue members in New Zealand, Australia, and Canada, we do expect to make this functionality available to more people in the near future and encourage you to prepare by getting familiar with this v2 functionality now. We are also exploring adding the ability to edit Tweets via the Twitter API v2 in the future.