Migrating from Activity Streams data format to v2

The Activity Streams data format is available with our enterprise products. If you are using the standard v1.1 endpoints, please refer to the standard v1.1 to v2 guide. If you are using the premium endpoints, or the Native Enriched format for enterprise, please refer to the Native Enriched to v2 guide.

Twitter API v2 introduces new JSON designs for Tweet and user objects.

  • At the JSON root level, the Activity Streams format returns Tweet objects in a results array, while Twitter API v2 returns a data array. 
  • Instead of referring to Retweeted and Quoted "activities", Twitter API v2 JSON refers to Retweeted and Quoted Tweets. 
  • Instead of using both favorites (in Tweet object) and favourites (in user object), Twitter API v2 uses the term like
  • Twitter is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Tweet and user attributes are only included if they have non-null values. 
  • All id fields in v2 will be in string format.
     

In addition to the changes made to the new JSON format, we also introduced a new set of fields to the Tweet object including the following:

  • conversation_id
  • reply_settings
  • alt_text on media
  • Two new annotations fields, including context and entities
  • Several new metrics fields
  • Several new polls fields
     

Many legacy and deprecated fields are being removed or replaced:

  • display_text_range
  • generator
  • gnip
  • link
  • objectType
  • provider
  • twitter_entities.symbols replaced with data.entities.cashtags
  • Certain twitter_extended_entities.media and twitter_entities.media fields
  • twitter_filter_level
  • twitterTimeZone
  • verb

Tweet object

Activity Streams format

Twitter v2 format

Required v2 parameters

Type in v2

postedTime

data.created_at

tweet.fields=created_at

Date (ISO 8601)

generator

Not Available

Not Available

 

generator.link

Not Available

Not Available

 

generator.displayName

data.source

tweet.fields=source

String

twitter_lang

data.lang

tweet.fields=lang

String

Not Available

data.conversation_id

tweet.fields=conversation_id

String

Not Available

data.reply_settings

tweet.fields=reply_settings

String

Not Available

data.possibly_sensitive

tweet.fields=possibly_sensitive

Boolean

Not Available

data.withheld

tweet.fields=withheld

Object

objectType

Not Available

Not Available

 

verb

Not Available

Not Available

 

provider

Not Available

Not Available

 

provider.objectType

Not Available

Not Available

 

provider.displayName

Not Available

Not Available

 

provider.link

Not Available

Not Available

 

link

Not Available

Not Available

 

display_text_range

Not Available

Not Available

 

object

Not Available

Not Available

 

object.objectType

Not Available

Not Available

 

object.id

Not Available

Not Available

 

object.summary

data.text

default

String

object.link

Not Available

Not Available

 

object.postedTime

data.created_at

tweet.fields=created_at

Date (ISO 8601)

Derived from actor.id

data.author_id

tweet.fields=created_at

 

twitter_filter_level

Not Available

Not Available

 

Derived from username in inReplyTo.link

data.in_reply_to_user_id

tweet.fields=in_reply_to_user_id

String

Not Available

data.referenced_tweets

tweet.fields=referenced_tweets

Array of objects

Not Available

data.referenced_tweets.type

tweet.fields=referenced_tweets

String

Derived from inReplyTo.link

data.referenced_tweets.id

tweet.fields=referenced_tweets

String

Not Available

data.attachments

tweet.fields=attachments

Object

Derived from twitter_entities.media.id_str

data.attachments.media_keys

tweet.fields=attachments

Array

Not Available

data.attachments.poll_ids

tweet.fields=attachments

Array

twitter_entities

data.entities

tweet.fields=entities

Object

Not Available

data.entities.annotations

tweet.fields=entities

Array of objects

Not Available

data.entities.annotations.start

tweet.fields=entities

Int

Not Available

data.entities.annotations.end

tweet.fields=entities

Int

Not Available

data.entities.annotations.probability

tweet.fields=entities

Float

Not Available

data.entities.annotations.type

tweet.fields=entities

String

Not Available

data.entities.annotations.normalized_text

tweet.fields=entities

String

twitter_entities.urls

data.entities.urls

tweet.fields=entities

Array of objects

twitter_entities.urls.indices[0]

data.entities.urls.start

tweet.fields=entities

Int

twitter_entities.urls.indices[1]

data.entities.urls.end

tweet.fields=entities

Int

twitter_entities.urls.url

data.entities.urls.url

tweet.fields=entities

String

twitter_entities.urls.expanded_url

data.entities.urls.expanded_url

tweet.fields=entities

String

twitter_entities.urls.display_url

data.entities.urls.display_url

tweet.fields=entities

String

Not Available

data.entities.urls.images

tweet.fields=entities

Array of objects

Not Available

data.entities.urls.images.url

tweet.fields=entities

String

Not Available

data.entities.urls.images.width

tweet.fields=entities

Int

Not Available

data.entities.urls.images.height

tweet.fields=entities

Int

gnip.urls.expanded_status

data.entities.urls.status

tweet.fields=entities

Int

gnip.urls.expanded_url_title

data.entities.urls.title

tweet.fields=entities

String

gnip.urls.expanded_url_description

data.entities.urls.description

tweet.fields=entities

String

gnip.urls.expanded_url

data.entities.urls.unwound_url

tweet.fields=entities

String

twitter_entities.symbols

data.entities.cashtags

tweet.fields=entities

Array of objects

twitter_entities.symbols.indices[0]

data.entities.cashtags.start

tweet.fields=entities

Int

twitter_entities.symbols.indices[1]

data.entities.cashtags.end

tweet.fields=entities

Int

twitter_entities.symbols.text

data.entities.cashtags.tag

tweet.fields=entities

String

twitter_entities.hashtags

data.entities.hashtags

tweet.fields=entities

Array of objects

twitter_entities.hashtags.indices[0]

data.entities.hashtags.start

tweet.fields=entities

Int

twitter_entities.hashtags.indices[1]

data.entities.hashtags.end

tweet.fields=entities

Int

twitter_entities.hashtags.text

data.entities.hashtags.tag

tweet.fields=entities

String

twitter_entities.user_mentions

data.entities.mentions

tweet.fields=entities

Array of objects

twitter_entities.user_mentions.indices[0]

data.entities.mentions.start

tweet.fields=entities

Int

twitter_entities.user_mentions.indices[1]

data.entities.mentions.end

tweet.fields=entities

Int

twitter_entities.user_mentions.screen_name

data.entities.mentions.tag

tweet.fields=entities

String

twitter_entities.user_mentions.id_str

data.entities.mentions.id

tweet.fields=entities

String

twitter_entities.user_mentions.id

Not Available

Not Available

 

Not Available

data.context_annotations

tweet.fields=context_annotations

Array of objects

Not Available

data.context_annotations.domain

tweet.fields=context_annotations

Object

Not Available

data.context_annotations.domain.id

tweet.fields=context_annotations

String

Not Available

data.context_annotations.domain.name

tweet.fields=context_annotations

String

Not Available

data.context_annotations.domain.description

tweet.fields=context_annotations

String

Not Available

data.context_annotations.entity

tweet.fields=context_annotations

Object

Not Available

data.context_annotations.entity.id

tweet.fields=context_annotations

String

Not Available

data.context_annotations.entity.name

tweet.fields=context_annotations

String

Not Available

data.context_annotations.entity.description

tweet.fields=context_annotations

String

geo

data.geo

tweet.fields=geo

Object

Derived from location.link

data.geo.place_id

tweet.fields=geo

String

Not Available

data.public_metrics

tweet.fields=public_metrics

Object

favoritesCount

data.public_metrics.like_count

tweet.fields=public_metrics

Int

retweetCount

data.public_metrics.retweet_count

tweet.fields=public_metrics

Int

Not Available

data.public_metrics.quote_count

tweet.fields=public_metrics

Int

Not Available

data.public_metrics.reply_count

tweet.fields=public_metrics

Int

Not Available

data.non_non_public_metrics

tweet.fields=non_public_metrics

Object

Not Available

data.non_public_metrics.impression_count

tweet.fields=non_public_metrics

Int

Not Available

data.non_public_metrics.url_link_count

tweet.fields=non_public_metrics

Int

Not Available

data.non_public_metrics.user_profile_count

tweet.fields=non_public_metrics

Int

Not Available

data.organic_metrics

tweet.fields=organic_metrics

Object

Not Available

data.organic_metrics.like_count

tweet.fields=organic_metrics

Int

Not Available

data.organic_metrics.retweet_count

tweet.fields=organic_metrics

Int

Not Available

data.organic_metrics.reply_count

tweet.fields=organic_metrics

Int

Not Available

data.organic_metrics.impression_count

tweet.fields=organic_metrics

Int

Not Available

data.organic_metrics.url_link_count

tweet.fields=organic_metrics

Int

Not Available

data.organic_metrics.user_profile_count

tweet.fields=organic_metrics

Int

Not Available

data.promoted_metrics

tweet.fields=promoted_metrics

Object

Not Available

data.promoted_metrics.like_count

tweet.fields=promoted_metrics

Int

Not Available

data.promoted_metrics.retweet_count

tweet.fields=promoted_metrics

Int

Not Available

data.promoted_metrics.reply_count

tweet.fields=promoted_metrics

Int

Not Available

data.promoted_metrics.impression_count

tweet.fields=promoted_metrics

Int

Not Available

data.promoted_metrics.url_link_count

tweet.fields=promoted_metrics

Int

Not Available

data.promoted_metrics.user_profile_count

tweet.fields=promoted_metrics

Int

gnip.profileLocations

Not Available

Not Available

 

gnip.profileLocations.address

Not Available

Not Available

 

gnip.profileLocations.address.country

Not Available

Not Available

 

gnip.profileLocations.address.countryCode

Not Available

Not Available

 

gnip.profileLocations.displayName

Not Available

Not Available

 

gnip.profileLocations.geo

Not Available

Not Available

 

gnip.profileLocations.geo.coordinates

Not Available

Not Available

 

gnip.profileLocations.geo.type

Not Available

Not Available

 

gnip.profileLocations.objectType

Not Available

Not Available

 

 


 

 

User object

Activity Streams format

Twitter v2 format

Required v2 parameters

Type in v2

actor

includes.users

expansions=author_id

Array of objects

Derived from actor.id

includes.users.id

expansions=author_id

String

actor.displayName

includes.users.name

expansions=author_id

String

actor.preferredUsername

includes.users.username

expansions=author_id

String

actor.postedTime

includes.users.created_at

expansions=author_id&user.fields=created_at

Date (ISO 8601)

actor.summary

includes.users.description

expansions=author_id&user.fields=description

String

Not Available

includes.users.pinned_tweet_id

expansions=author_id&user.fields=pinned_tweet_id

String

Not Available

includes.users.protected

expansions=author_id&user.fields=protected

Boolean

actor.link

Not Available

Not Available - construct from includes.users.username

 

actor.twitterTimeZone

Not Available

Not Available - infer from Tweet created_at

 

actor.utcOffset

Not Available

Not Available - infer from Tweet created_at

 

actor.favoritesCount

Not Available

Not Available

 

actor.followersCount

includes.users.public_metrics.followers_count

expansions=author_id&user.fields=public_metrics

Int

actor.friendsCount

includes.users.public_metrics.following_count

expansions=author_id&user.fields=public_metrics

Int

actor.listedCount

includes.users.public_metrics.listed_count

expansions=author_id&user.fields=public_metrics

Int

actor.statusesCount

includes.users.public_metrics.tweet_count

expansions=author_id&user.fields=public_metrics

Int

actor.languages[]

Not Available

Not Available -  infer from Tweet  lang

 

actor.location.displayName

includes.users.location

expansions=author_id&user.fields=location

String

actor.image

includes.users.profile_image_url

expansions=author_id&user.fields=profile_image_url

String

actor.links

includes.users.url

expansions=author_id&user.fields=url

String

actor.verified

includes.users.verified

expansions=author_id&user.fields=verified

Boolean

Not Available

includes.users.withheld

expansions=author_id&user.fields=withheld

Object

Not Available

includes.users.entities

expansions=author_id&user.fields=entities

Object

Not Available

includes.users.entities.url

expansions=author_id&user.fields=entities

Object

actor.links

includes.users.entities.url.urls

expansions=author_id&user.fields=entities

Array of objects

Not Available

includes.users.entities.url.urls.start

expansions=author_id&user.fields=entities

Int

Not Available

includes.users.entities.url.urls.end

expansions=author_id&user.fields=entities

Int

Not Available

includes.users.entities.url.urls.url

expansions=author_id&user.fields=entities

String

actor.links.href

includes.users.entities.url.urls.expanded_url

expansions=author_id&user.fields=entities

String

Not Available

includes.users.entities.url.urls.display_url

expansions=author_id&user.fields=entities

String

Not Available

includes.users.entities.description

expansions=author_id&user.fields=entities

Object

Not Available

includes.users.entities.description.hashtags

expansions=author_id&user.fields=entities

Array of objects

Not Available

includes.users.entities.description.hashtags.start

expansions=author_id&user.fields=entities

Int

Not Available

includes.users.entities.description.hashtags.end

expansions=author_id&user.fields=entities

Int

Not Available

includes.users.entities.description.hashtags.tag

expansions=author_id&user.fields=entities

String

Not Available

includes.users.entities.description.mentions

expansions=author_id&user.fields=entities

Array of objects

Not Available

includes.users.entities.description.mentions.start

expansions=author_id&user.fields=entities

Int

Not Available

includes.users.entities.description.mentions.end

expansions=author_id&user.fields=entities

Int

Not Available

includes.users.entities.description.mentions.username

expansions=author_id&user.fields=entities

String

Not Available

includes.users.entities.description.cashtags

expansions=author_id&user.fields=entities

Array of objects

Not Available

includes.users.entities.description.cashtags.start

expansions=author_id&user.fields=entities

Int

Not Available

includes.users.entities.description.cashtags.end

expansions=author_id&user.fields=entities

Int

Not Available

includes.users.entities.description.cashtags.tag

expansions=author_id&user.fields=entities

String

 


 

 

Poll object

Activity Streams format

Twitter v2 format

Required v2 parameters

Type in v2

Not Available

includes.polls

expansions=attachments.poll_ids

Array of objects

Not Available

includes.polls.id

expansions=attachments.poll_ids

String

Not Available

includes.polls.options

expansions=attachments.poll_ids

Array of objects

Not Available

includes.polls.options.position

expansions=attachments.poll_ids

Int

Not Available

includes.polls.options.label

expansions=attachments.poll_ids

String

Not Available

includes.polls.options.votes

expansions=attachments.poll_ids

Int

Not Available

includes.polls.voting_status

expansions=attachments.poll_ids&poll.fields=voting_status

String

Not Available

includes.polls.duration_minutes

expansions=attachments.poll_ids&poll.fields=duration_minutes

Int

Not Available

includes.polls.end_datetime

expansions=attachments.poll_ids&poll.fields=end_datetime

Date (ISO 8601)

 


 

 

Place object

Activity Streams format

Twitter v2 format

Required v2 parameters

Type in v2

location

includes.places

expansions=geo.place_id

array of objects

location.displayName

includes.places.full_name

expansions=geo.place_id

string

Parsed from location.link

includes.places.id

expansions=geo.place_id

string

location.name

includes.places.name

expansions=geo.place_id&place.fields=name

string

location.country_code

includes.places.country

expansions=geo.place_id&place.fields=country

string

location.twitter_place_type

includes.places.place_type

expansions=geo.place_id&place.fields=place_type

string

location.twitter_country_code

includes.places.country_code

expansions=geo.place_id&place.fields=country_code

string

location.geo

includes.places.geo

expansions=geo.place_id&place.fields=geo

object

location.geo.type

includes.places.geo.type

expansions=geo.place_id&place.fields=geo

string

location.geo.coordinates

includes.places.geo.bbox

expansions=geo.place_id&place.fields=geo

array

Not Available

includes.places.geo.properties

expansions=geo.place_id&place.fields=geo

object

 


 

 

Media object

Activity Streams format

Twitter v2 format

Required v2 parameters

Type in v2

twitter_entities.media OR twitter_extended_entities.media

includes.media

expansions=attachments.media_keys

Array of objects

twitter_entities.media.id_str OR twitter_extended_entities.media.id_str

includes.media.media_key

expansions=attachments.media_keys

String

twitter_entities.media.id OR twitter_extended_entities.media.id

Not available

Not available

 

twitter_entities.media.indices OR twitter_extended_entities.media.indices

Not available

Not available

 

twitter_entities.media.additional_media_info OR twitter_extended_entities.media.additional_media_info

Not available

Not available

 

twitter_entities.media.additional_media_info.monetizable OR twitter_extended_entities.media.additional_media_info.monetizable

Not available

Not available

 

twitter_entities.media.media_url OR twitter_extended_entities.media.media_url

Not available

Not available

 

twitter_entities.media.media_url_https OR twitter_extended_entities.media.media_url_https

includes.media.preview_image_url

expansions=attachments.media_keys&media.fields=preview_image_url

String

twitter_entities.media.url OR twitter_extended_entities.media.url

Not available

Not available

 

twitter_entities.media.display_url OR twitter_extended_entities.media.display_url

Not available

Not available

 

twitter_entities.media.expanded_url OR twitter_extended_entities.media.expanded_url

Not available

Not available

 

twitter_entities.media.type OR twitter_extended_entities.media.type

includes.media.type

expansions=attachments.media_keys

String

twitter_entities.media.sizes OR twitter_extended_entities.media.sizes

Not available

Not available

 

twitter_entities.media.sizes.thumb OR twitter_extended_entities.media.sizes.thumb

Not available

Not available

 

twitter_entities.media.sizes.thumb.h OR twitter_extended_entities.media.sizes.thumb.h

Not available

Not available

 

twitter_entities.media.sizes.thumb.w OR twitter_extended_entities.media.sizes.thumb.w

Not available

Not available

 

twitter_entities.media.sizes.thumb.resize OR twitter_extended_entities.media.sizes.thumb.resize

Not available

Not available

 

twitter_entities.media.sizes.small OR twitter_extended_entities.media.sizes.small

Not available

Not available

 

twitter_entities.media.sizes.small.h OR twitter_extended_entities.media.sizes.small.h

Not available

Not available

 

twitter_entities.media.sizes.small.w OR twitter_extended_entities.media.sizes.small.w

Not available

Not available

 

twitter_entities.media.sizes.small.resize OR twitter_extended_entities.media.sizes.small.resize

Not available

Not available

 

twitter_entities.media.sizes.medium OR twitter_extended_entities.media.sizes.medium

Not available

Not available

 

twitter_entities.media.sizes.medium.h OR twitter_extended_entities.media.sizes.medium.h

Not available

Not available

 

twitter_entities.media.sizes.medium.w OR twitter_extended_entities.media.sizes.medium.w

Not available

Not available

 

twitter_entities.media.sizes.medium.resize OR twitter_extended_entities.media.sizes.medium.resize

Not available

Not available

 

twitter_entities.media.sizes.large OR twitter_extended_entities.media.sizes.large

Not available

Not available

 

twitter_entities.media.sizes.large.h OR twitter_extended_entities.media.sizes.large.h

includes.media.height

expansions=attachments.media_keys&media.fields=height

Int

twitter_entities.media.sizes.large.w OR twitter_extended_entities.media.sizes.large.w

includes.media.width

expansions=attachments.media_keys&media.fields=width

Int

twitter_entities.media.sizes.large.resize OR twitter_extended_entities.media.sizes.large.resize

Not available

Not available

 

twitter_extended_entities.media.video_info

Not available

Not available

 

twitter_extended_entities.media.video_info.aspect_ratio

Not available

Not available

 

twitter_extended_entities.media.video_info.duration_millis

includes.media.duration_ms

expansions=attachments.media_keys&media.fields=duration_ms

Int

twitter_extended_entities.media.video_info.variants

Not available

Not available

 

twitter_extended_entities.media.video_info.variants.bitrate

Not available

Not available

 

twitter_extended_entities.media.video_info.variants.content_type

Not available

Not available

 

twitter_extended_entities.media.video_info.variants.url

Not available

Not available

 

Not available

includes.media.alt_text

expansions=attachments.media_keys&media.fields=alt_text

String

Not available

includes.media.public_metrics

expansions=attachments.media_keys&media.fields=public_metrics

Object

Not available

includes.media.public_metrics.view_count

expansions=attachments.media_keys&media.fields=public_metrics

Int

Not available

includes.media.non_public_metrics

expansions=attachments.media_keys&media.fields=non_public_metrics

Object

Not available

includes.media.non_public_metrics.playback_0_count

expansions=attachments.media_keys&media.fields=non_public_metrics

Int

Not available

includes.media.non_public_metrics.playback_25_count

expansions=attachments.media_keys&media.fields=non_public_metrics

Int

Not available

includes.media.non_public_metrics.playback_50_count

expansions=attachments.media_keys&media.fields=non_public_metrics

Int

Not available

includes.media.non_public_metrics.playback_75_count

expansions=attachments.media_keys&media.fields=non_public_metrics

Int

Not available

includes.media.non_public_metrics.playback_100_count

expansions=attachments.media_keys&media.fields=non_public_metrics

Int

Not available

includes.media.organic_metrics

expansions=attachments.media_keys&media.fields=organic_metrics

Object

Not available

includes.media.organic_metrics.playback_0_count

expansions=attachments.media_keys&media.fields=organic_metrics

Int

Not available

includes.media.organic_metrics.playback_25_count

expansions=attachments.media_keys&media.fields=organic_metrics

Int

Not available

includes.media.organic_metrics.playback_50_count

expansions=attachments.media_keys&media.fields=organic_metrics

Int

Not available

includes.media.organic_metrics.playback_75_count

expansions=attachments.media_keys&media.fields=organic_metrics

Int

Not available

includes.media.organic_metrics.playback_100_count

expansions=attachments.media_keys&media.fields=organic_metrics

Int

Not available

includes.media.organic_metrics.view_count

expansions=attachments.media_keys&media.fields=organic_metrics

Int

Not available

includes.media.promoted_metrics

expansions=attachments.media_keys&media.fields=promoted_metrics

Object

Not available

includes.media.promoted_metrics.playback_0_count

expansions=attachments.media_keys&media.fields=promoted_metrics

Int

Not available

includes.media.promoted_metrics.playback_25_count

expansions=attachments.media_keys&media.fields=promoted_metrics

Int

Not available

includes.media.promoted_metrics.playback_50_count

expansions=attachments.media_keys&media.fields=promoted_metrics

Int

Not available

includes.media.promoted_metrics.playback_75_count

expansions=attachments.media_keys&media.fields=promoted_metrics

Int

Not available

includes.media.promoted_metrics.playback_100_count

expansions=attachments.media_keys&media.fields=promoted_metrics

Int

Not available

includes.media.promoted_metrics.view_count

expansions=attachments.media_keys&media.fields=promoted_metrics

Int

 


 

 

Matching rules object

Activity Streams format

Twitter v2 format

Required v2 parameters

Type in v2

gnip.matching_rules

matching_rules

Default in filtered stream

Array of objects

gnip.matching_rules.tag

matching_rules.tag

Default in filtered stream

String

gnip.matching_rules.tag.id

Not Available

Not Available

 

gnip.matching_rules.tag.id_str

matching_rules.id

Default in filtered stream

String

Was this document helpful?
Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?
Thank you for the feedback. Your comments will help us improve our documents in the future.