add public_metrics.bookmarkcount and non_public_metrics.engagements

Author: tcaldwell-x

x-api/fundamentals/data-dictionary.mdx

@@ -56,12 +56,12 @@ Use `tweet.fields` to request additional fields and `expansions` to include rela
 | **geo**          | object | Indicates the location or place of a geo-tagged Tweet.                                       | Use this to determine get location of a geo-tagged Tweet. |
 | **in_reply_to_user_id** | string | If the represented Tweet is a reply, this field will contain the original Tweet’s author ID.                                       | Determine if a Tweet was in reply to another Tweet.                  |
 | **lang**              | string | Language of the Tweet, if detected by Twitter.                                                                                      | Classify Tweets by spoken language.                                  |
-| **non_public_metrics** | object | Non-public engagement metrics for the Tweet at the time of the request. Requires user context authentication.                       | Determine total impressions generated for the Tweet.                 |
+| **non_public_metrics** | object | Non-public engagement metrics for the Tweet at the time of the request. Requires user context authentication. Includes `impression_count`, `user_profile_clicks`, `url_link_clicks`, and `engagements`.                       | Determine total impressions and engagement generated for the Tweet.                 |
 | **note_tweet** | object | Contains the full text of a Post for long-form Posts (>280 characters).                       | Get the complete text of a post.                 |
 | **organic_metrics**   | object | Engagement metrics, tracked in an organic context, for the Tweet at the time of the request. Requires user context authentication.  | Measure organic engagement for the Tweet.                            |
 | **possibly_sensitive** | boolean | Indicates if the content may be recognized as sensitive.                                                                           | Study circulation of certain types of content.                       |
 | **promoted_metrics**  | object | Engagement metrics, tracked in a promoted context, for the Tweet at the time of the request. Requires user context authentication. | Measure engagement for the Tweet when it was promoted.               |
-| **public_metrics**    | object | Public engagement metrics for the Tweet at the time of the request.                                                                 | Measure Tweet engagement.                                            |
+| **public_metrics**    | object | Public engagement metrics for the Tweet at the time of the request. Includes `retweet_count`, `reply_count`, `like_count`, `quote_count`, `impression_count`, and `bookmark_count`.                                                                 | Measure Tweet engagement.                                            |
 | **referenced_tweets** | array  | A list of Tweets this Tweet refers to, such as Retweets, quoted Tweets, or replies.                                                | Understand conversational aspects of retweets, etc.                  |
 | **reply_settings**    | string | Shows who can reply to a given Tweet. Options are "everyone", "mentioned_users", and "followers".                                  | Determine conversation reply settings for the Tweet.                 |
 | **withheld**          | object | Contains withholding details for [withheld content](https://help.x.com/en/rules-and-policies/tweet-withheld-by-country).     |                                                                     |
@@ -130,7 +130,9 @@ curl --request GET 'https://api.x.com/2/tweets?ids=1212092628029698048&tweet.fie
         "retweet_count": 7,
         "reply_count": 3,
         "like_count": 38,
-        "quote_count": 1
+        "quote_count": 1,
+        "bookmark_count": 2,
+        "impression_count": 1250
       },
       "context_annotations": [
         {
@@ -305,7 +307,9 @@ curl --request GET 'https://api.x.com/2/tweets?ids=1212092628029698048&tweet.fie
           "retweet_count": 2,
           "reply_count": 1,
           "like_count": 19,
-          "quote_count": 0
+          "quote_count": 0,
+          "bookmark_count": 0,
+          "impression_count": 430
         },
         "created_at": "2019-12-31T19:26:16.000Z",
         "possibly_sensitive": false

x-api/fundamentals/fields.mdx

@@ -62,7 +62,9 @@ Response:
       "retweet_count": 10,
       "reply_count": 5,
       "like_count": 100,
-      "quote_count": 2
+      "quote_count": 2,
+      "bookmark_count": 3,
+      "impression_count": 1500
     }
   }
 }
@@ -176,7 +178,7 @@ media.fields=url,preview_image_url,alt_text,public_metrics
 ## Important notes
 
 <Warning>
-**You cannot request subfields.** When you request `public_metrics`, you get all metrics (likes, reposts, replies, quotes). You can't request just `public_metrics.like_count`.
+**You cannot request subfields.** When you request `public_metrics`, you get all metrics (likes, reposts, replies, quotes, bookmarks, impressions). You can't request just `public_metrics.like_count`.
 </Warning>
 
 - Field order in responses may differ from request order

x-api/fundamentals/metrics.mdx

@@ -35,8 +35,10 @@ The X API provides engagement metrics for posts and media. Access public metrics
 | Likes | Public | `public_metrics.like_count` |
 | Replies | Public | `public_metrics.reply_count` |
 | Impressions | Public | `public_metrics.impression_count` |
+| Bookmarks | Public | `public_metrics.bookmark_count` |
 | URL clicks | Non-public | `non_public_metrics.url_link_clicks` |
 | Profile clicks | Non-public | `non_public_metrics.user_profile_clicks` |
+| Engagements | Non-public | `non_public_metrics.engagements` |
 
 ### Media metrics (videos)
 
@@ -71,7 +73,9 @@ Response:
       "retweet_count": 50,
       "reply_count": 12,
       "like_count": 234,
-      "quote_count": 5
+      "quote_count": 5,
+      "bookmark_count": 8,
+      "impression_count": 5432
     }
   }
 }
@@ -96,7 +100,8 @@ Response:
     "non_public_metrics": {
       "impression_count": 5432,
       "url_link_clicks": 89,
-      "user_profile_clicks": 156
+      "user_profile_clicks": 156,
+      "engagements": 345
     },
     "organic_metrics": {
       "impression_count": 5432,
@@ -188,6 +193,10 @@ Number of reposts (retweets). Does not include quote posts.
 Number of quote posts (reposts with comment). These are always organic.
 </Accordion>
 
+<Accordion title="Bookmark count">
+Number of times the post has been bookmarked by users.
+</Accordion>
+
 <Accordion title="Video views">
 Aggregated across all posts containing the video. A video reposted in multiple posts has one total view count.
 </Accordion>

x-api/posts/timelines/integrate.mdx

@@ -287,7 +287,9 @@ Available for all Posts with App-Only or User Context authentication:
     "retweet_count": 156,
     "reply_count": 23,
     "like_count": 892,
-    "quote_count": 12
+    "quote_count": 12,
+    "bookmark_count": 34,
+    "impression_count": 15200
   }
 }
 ```

x-api/posts/timelines/migrate/overview.mdx

@@ -35,7 +35,7 @@ The following tables compare the standard v1.1 and X API v2 home timeline endpoi
 | Timeline navigation options | since_id (exclusive) used for update polling<br/><br/>`max_id` (inclusive) | `start_time`<br/><br/>end_time<br/><br/>`since_id`(exclusive) used for update polling <br/><br/>`until_id` (exclusive) |
 | Optional parameters for results refinement | `count`<br/><br/>`exclude_replies`<br/><br/>`include_rts`<br/><br/>`trim_user`<br/><br/>`tweet_mode`<br/><br/>`since_id`<br/><br/>`max_id` | `max_results`<br/><br/>`exclude`(retweets,replies)<br/><br/>`tweet.fields`<br/><br/>`user.fields`<br/><br/>`place.fields`<br/><br/>`media.fields`<br/><br/>`poll.fields`<br/><br/>`expansions`<br/><br/>`start_time`<br/><br/>`end_time`<br/><br/>`since_id`<br/><br/>`until_id` |
 | Supports requesting and receiving [annotations](/x-api/fundamentals/post-annotations) | N/A | If annotations are included in tweet.fields, results will be annotated with inferred annotation data based on the Post text, such as 'Music Genre' and 'Folk Music' or 'Musician' and 'Dolly Parton' |
-| Supports requesting and receiving specific Post [metrics](/x-api/fundamentals/metrics) | N/A | If annotations are included in `tweet.fields`, results will be annotated with public_metrics per Post including `retweet_count`, `reply_count`, `quote_count` and `like_count`, `non_public_metrics` , including `impression_count`, `user_profile_clicks`, `url_link_clicks`.<br/><br/>Additional media metrics such as view_count and video playback metrics.<br/><br/>Additional organic\_metrics and promoted\_metrics available with User Context for promoted Posts. |
+| Supports requesting and receiving specific Post [metrics](/x-api/fundamentals/metrics) | N/A | If annotations are included in `tweet.fields`, results will be annotated with public_metrics per Post including `retweet_count`, `reply_count`, `quote_count`, `like_count`, `impression_count`, and `bookmark_count`, `non_public_metrics` including `impression_count`, `user_profile_clicks`, `url_link_clicks`, and `engagements`.<br/><br/>Additional media metrics such as view_count and video playback metrics.<br/><br/>Additional organic\_metrics and promoted\_metrics available with User Context for promoted Posts. |
 | Supports requesting and receiving [conversation_id](/x-api/fundamentals/conversation-id) | N/A | Returns a conversation_id field where the value represents the first published Post in a reply thread to help you track conversations. |
 | Post JSON format | [Standard v1.1 data format](https://developer.x.com/en/docs/twitter-api/v1/data-dictionary/overview.html) | [X API v2](/x-api/fundamentals/data-dictionary) format (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)<br/><br/>To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). |
 | Results order | Reverse chronological | Reverse chronological |