Add itemCount to List API [BETA] (#28278)

* add itemsCount

* nit

* Update whats-new-overview.md

* Update list.md

* Revise list-get.md with new examples and instructions

Updated examples and request body instructions in the list-get documentation.

* Modify request block type in list-get.md

Updated the example request block type in the documentation.

* Update whats-new-overview.md

* Apply suggestion from @FaithOmbongi

---------

Co-authored-by: MSFT-Andrea <v-andreadr@microsoft.com>
Co-authored-by: Faith Moraa Ombongi <ombongi.moraa.fe@gmail.com>

Author: 3 people

api-reference/beta/api/list-get.md

@@ -36,12 +36,14 @@ GET /sites/{site-id}/lists/{list-id}?expand=columns,items(expand=fields)
 
 ## Request body
 
-Do not supply a request body with this method.
+Don't supply a request body with this method.
 
-## Example
+## Examples
 
+### Example 1: Get list metadata by ID
+The following example shows how to get the metadata for a SharePoint list.
 #### Request
-
+The following examples shows a request.
 
 # [HTTP](#tab/http)
 <!-- { "blockType": "request", "name": "get-list-1" } -->
@@ -81,7 +83,7 @@ GET /sites/{site-id}/lists/{list-id}
 ---
 
 #### Response
-
+The following examples shows the response.
 <!-- { "blockType": "response", "@type": "microsoft.graph.list", "truncated": true, "scopes": "sites.read.all service.sharepoint" } -->
 
 ```http
@@ -93,17 +95,18 @@ Content-type: application/json
   "name": "MicroFeed",
   "createdDateTime": "2016-08-30T08:32:00Z",
   "lastModifiedDateTime": "2016-08-30T08:32:00Z",
+  "itemCount": 127,
   "list": {
     "hidden": false,
     "template": "genericList"
     }
 }
 ```
 
-With `select` and `expand` statements, you can retrieve list metadata, column definitions, and list items in a single request.
-
-#### Request
+### Example 2: Get list metadata by title
 The following example shows how to get a list from a SharePoint Online list title.
+#### Request
+The following example shows a request.
 
 # [HTTP](#tab/http)
 <!-- { "blockType": "request", "name": "get-list-2" } -->
@@ -143,7 +146,7 @@ GET /sites/{site-id}/lists/{list-title}
 ---
 
 #### Response
-
+The following example shows the response.
 <!-- { "blockType": "response", "@type": "microsoft.graph.list", "truncated": true, "scopes": "sites.read.all service.sharepoint" } -->
 
 ```http
@@ -155,23 +158,25 @@ Content-type: application/json
   "name": "MicroFeed",
   "createdDateTime": "2016-08-30T08:32:00Z",
   "lastModifiedDateTime": "2016-08-30T08:32:00Z",
+  "itemCount": 45,
   "list": {
     "hidden": false,
     "template": "genericList"
     }
 }
 ```
 
-With `select` and `expand` statements, you can retrieve list metadata, column definitions, and list items in a single request.
+### Example 3: Get list metadata and items with $select and $expand
+The following example shows how to use the `$select` and `$expand` OData query parameters to retrieve list metadata, column definitions, and list items in a single request.
 
 #### Request
-
+The following example shows a request.
 
 # [HTTP](#tab/http)
 <!-- { "blockType": "request", "name": "get-list-multi-expand" } -->
 
 ```msgraph-interactive
-GET /sites/{site-id}/lists/{list-id}?select=name,lastModifiedDateTime&expand=columns(select=name,description),items(expand=fields(select=Name,Color,Quantity))
+GET /sites/{site-id}/lists/{list-id}?select=name,lastModifiedDateTime,itemCount&expand=columns(select=name,description),items(expand=fields(select=Name,Color,Quantity))
 ```
 
 # [C#](#tab/csharp)
@@ -205,7 +210,7 @@ GET /sites/{site-id}/lists/{list-id}?select=name,lastModifiedDateTime&expand=col
 ---
 
 #### Response
-
+The following example shows the response.
 <!-- { "blockType": "response", "@type": "microsoft.graph.list", "truncated": true, "scopes": "sites.read.all service.sharepoint" } -->
 
 ```http
@@ -254,21 +259,24 @@ Content-type: application/json
         "Quantity": 92
        }
     }
-  ]
+  ],
+  "itemCount": 45
 }
 ```
-#### Request
 
-<!-- { "blockType": "request", "name": "get-list-multi-expand" } -->
+### Example 4: Get list metadata and items with multiple $expand parameters
+The following example shows how to get metadata and items for a list that contains three columns: *Name*, *Quantity*, and *Category*. [Managed metadata](/sharepoint/managed-metadata) columns like *Category* return values as term ID and term name pair.
+
+#### Request
+The following example shows a request.
+<!-- { "blockType": "request", "name": "get-list-multi-expand_4" } -->
 
-The following example shows how to get metadata for a list that contains three columns: Name, Quantity, and Category.
-[Managed Metadata](/sharepoint/managed-metadata) columns like ```Category``` return values as term ID and term name pair.
 ```http
 GET /sites/{site-id}/lists/{list-id}?select=name,lastModifiedDateTime&expand=columns(select=name,description),items(expand=fields(select=Name,Quantity,Category))
 ```
 
 #### Response
-
+The following example shows the response.
 <!-- { "blockType": "response", "@type": "microsoft.graph.list", "truncated": true, "scopes": "sites.read.all service.sharepoint" } -->
 
 ```http

api-reference/beta/api/list-list.md

@@ -108,6 +108,7 @@ Content-type: application/json
       "name": "Documents",
       "createdDateTime": "2016-08-30T08:32:00Z",
       "lastModifiedDateTime": "2016-08-30T08:32:00Z",
+      "itemCount": 312,
       "list": {
         "hidden": false,
         "template": "documentLibrary"
@@ -118,6 +119,7 @@ Content-type: application/json
       "name": "MicroFeed",
       "createdDateTime": "2016-08-30T08:32:00Z",
       "lastModifiedDateTime": "2016-08-30T08:32:00Z",
+      "itemCount": 45,
       "list": {
         "hidden": false,
         "template": "genericList"

api-reference/beta/resources/list.md

@@ -50,7 +50,7 @@ Represents a list in a [site](site.md). This resource contains the top level pro
 | displayName          | String                            | The displayable title of the list.                                                                    |
 | eTag                 | String                            | ETag for the item. Inherited from [baseItem](baseitem.md).                                            |
 | id                   | String                            | The unique identifier of the item. Read-only. Inherited from [baseItem](baseitem.md).                 |
-| itemCount            | Int32                             | The number of items in the list. Read-only.                                                           |
+| itemCount            | Int32                             | The total count of items in the list. Read-only.                                                           |
 | lastModifiedBy       | [identitySet](identityset.md)     | Identity of the last modifier of this item. Read-only. Inherited from [baseItem](baseitem.md).        |
 | lastModifiedDateTime | DateTimeOffset                    | The date and time when the item was last modified. Read-only. Inherited from [baseItem](baseitem.md). |
 | list                 | [listInfo](listinfo.md)           | Contains more details about the list.                                                                 |
@@ -90,6 +90,7 @@ The following JSON representation shows the resource type.
   "displayName": "String",
   "eTag": "String",
   "id": "String (identifier)",
+  "itemCount": "Int32",
   "lastModifiedBy": { "@odata.type": "microsoft.graph.identitySet" },
   "lastModifiedDateTime": "String (timestamp)",
   "list": { "@odata.type": "microsoft.graph.listInfo" },

changelog/Microsoft.FileServices.json

@@ -1,5 +1,23 @@
 {
   "changelog": [
+    {
+      "ChangeList": [
+        {
+          "Id": "5d6e9a5b-3c66-40c9-b3dd-a6fa374f1240",
+          "ApiChange": "Property",
+          "ChangedApiName": "itemCount",
+          "ChangeType": "Addition",
+          "Description": "Added the **itemCount** property to the [list](https://learn.microsoft.com/en-us/graph/api/resources/list?view=graph-rest-beta) resource.",
+          "Target": "list"
+        }
+      ],
+      "Id": "5d6e9a5b-3c66-40c9-b3dd-a6fa374f1240",
+      "Cloud": "Prod",
+      "Version": "beta",
+      "CreatedDateTime": "2026-04-24T23:41:39.1409717Z",
+      "WorkloadArea": "Files",
+      "SubArea": "" 
+    },
     {
       "ChangeList": [
         {

concepts/whats-new-overview.md

@@ -72,7 +72,8 @@ Added the **deprecationDate** property to the [applicationTemplate](/graph/api/r
 
 ### Files
 
-Use the **height** and **width** query parameters on the [driveItem content conversion API](/graph/api/driveitem-get-content-format?view=graph-rest-beta&preserve-view=true) to download a file in another format when `format=jpg`.
+- Use the **height** and **width** query parameters on the [driveItem content conversion API](/graph/api/driveitem-get-content-format?view=graph-rest-beta&preserve-view=true) to download a file in another format when `format=jpg`.
+- Use the **itemCount** property on the [list](/graph/api/resources/list?view=graph-rest-beta&preserve-view=true) resource to quickly access the total number of items in a SharePoint list without retrieving all items or making additional queries.
 
 ### Identity and access | Governance
 
@@ -242,7 +243,6 @@ Use the [follow user](/graph/api/storyline-follow?view=graph-rest-beta&preserve-
 - Use the [list](/graph/api/filestoragecontainertype-list-permissions?view=graph-rest-beta&preserve-view=true), [create](/graph/api/filestoragecontainertype-post-permissions?view=graph-rest-beta&preserve-view=true), [get](/graph/api/filestoragecontainertype-get-permission?view=graph-rest-beta&preserve-view=true), and [delete](/graph/api/filestoragecontainertype-delete-permissions?view=graph-rest-beta&preserve-view=true) APIs to manage user permissions for SharePoint Embedded [file storage container types](/graph/api/resources/filestoragecontainertype?view=graph-rest-beta&preserve-view=true).
 - [Archive](/graph/api/filestoragecontainer-archive?view=graph-rest-beta&preserve-view=true) or [unarchive](/graph/api/filestoragecontainer-unarchive?view=graph-rest-beta&preserve-view=true) a SharePoint Embedded storage container.
 - Requests made using the [list containers](/graph/api/filestorage-list-containers?view=graph-rest-beta&preserve-view=true) API without a user context (app-only authentication) aren't currently supported for multi-geo tenants.
-- Use the **itemCount** property on the [list](/graph/api/resources/list?view=graph-rest-beta&preserve-view=true) resource to quickly access the total number of items in a SharePoint list without retrieving all items or making additional queries.
 - Use the **principalId** property on [sharePointGroup](/graph/api/resources/sharepointgroup?view=graph-rest-beta&preserve-view=true) to get the principal ID of the SharePoint group in the tenant.
 - Use the **sharePointGroup** property on [sharePointIdentitySet](/graph/api/resources/sharepointidentityset?view=graph-rest-beta&preserve-view=true) to get the SharePoint group associated with a **sharePointIdentitySet** object.