List thumbnails for a DriveItem

Namespace: microsoft.graph

Retrieve a collection of ThumbnailSet resources for a DriveItem resource.

A DriveItem can be represented by zero or more ThumbnailSet resources. Each thumbnailSet can have one or more thumbnail objects, which are images that represent the item. For example, a thumbnailSet may include thumbnail objects, such as common ones including small, medium, or large.

There are many ways to work with thumbnails on OneDrive. Here are the most common ones:

• Enumerate available thumbnails for an item
• Retrieve a single thumbnail for an item
• Retrieve thumbnail content
• Retrieve thumbnails for multiple items in a single request
• Retrieve custom thumbnail sizes
• Upload a custom thumbnail for an item
• Determine if a custom uploaded thumbnail exists

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type	Least privileged permissions	Higher privileged permissions
Delegated (work or school account)	Files.Read	Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegated (personal Microsoft account)	Files.Read	Files.Read.All, Files.ReadWrite, Files.ReadWrite.All
Application	Files.Read.All	Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

HTTP request

GET /drives/{drive-id}/items/{item-id}/thumbnails
GET /groups/{group-id}/drive/items/{item-id}/thumbnails
GET /me/drive/items/{item-id}/thumbnails
GET /sites/{site-id}/drive/items/{item-id}/thumbnails
GET /users/{user-id}/drive/items/{item-id}/thumbnails

Optional query parameters

This method supports the $select OData query parameter to customize the response.

Additionally, this method supports retrieving the thumbnail with the original orientation EXIF value and without the applied rotation by appending the originalOrientation=true query parameter. This is currently only supported on OneDrive Personal.

Request headers

Name	Description
Authorization	Bearer {token}. Required. Learn more about authentication and authorization.

Response

If successful, this method returns a 200 OK response code and collection of ThumbnailSet objects in the response body.

Example

The following example shows a request which retrieves available thumbnails for an item in the current user's OneDrive.

HTTP

GET /me/drive/items/{item-id}/thumbnails

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Thumbnails.GetAsync();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

mgc drives items thumbnails list --drive-id {drive-id} --drive-item-id {driveItem-id}

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
thumbnails, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Thumbnails().Get(context.Background(), nil)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ThumbnailSetCollectionResponse result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").thumbnails().get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let thumbnails = await client.api('/me/drive/items/{item-id}/thumbnails')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->thumbnails()->get()->wait();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Files

Get-MgDriveItemThumbnail -DriveId $driveId -DriveItemId $driveItemId

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').thumbnails.get()

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

This returns an array of available thumbnailSets for the item. Any item in a drive can have zero or more thumbnails.

Note: You can use the select query string parameter to control which thumbnail sizes are returned in the ThumbnailSet. For example, /thumbnails?select=medium retrieves only the medium sized thumbnails.

Response

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "0",
      "small": { "height": 64, "width": 96, "url": "https://sn3302files..."},
      "medium": { "height": 117, "width": 176, "url": "https://sn3302files..."},
      "large": { "height": 533, "width": 800, "url": "https://sn3302files..."}
    }
  ]
}

Get a single thumbnail

Retrieve the metadata for a single thumbnail and size by addressing it directly in a request.

HTTP request

HTTP

GET /me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}

C#

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let response = await client.api('/me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Path parameters

Name	Type	Description
item-id	string	The unique identifier for the item referenced.
thumb-id	number	The index of the thumbnail, usually 0-4. If there is a custom thumbnail, its index is 0.
size	string	The size of the thumbnail requested. This can be one of the standard sizes listed below or a custom size.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "width": 100,
  "height": 100,
  "url": "https://onedrive.com/asd123a/asdjlkasjdkasdjlk.jpg"
}

Retrieve thumbnail binary content

You can directly retrieve the content of the thumbnail by requesting the content property of the thumbnail.

HTTP request

HTTP

GET /me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}/content

C#

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let content = await client.api('/me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}/content')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

The service responds with a redirect to the thumbnail URL.

HTTP/1.1 302 Found
Location: https://b0mpua-by3301.files.1drv.com/y23vmagahszhxzlcvhasdhasghasodfi

Thumbnail URLs are cache-safe. The URL will change, if the item changes in a way that requires a new thumbnail to be generated.

Getting thumbnails while listing DriveItems

If you are retrieving a list of DriveItem resources to display, you can use the $expand query string parameter to also include the thumbnails for those resources. This enables your app to retrieve thumbnails and items in a single request, instead of issuing many requests.

HTTP request

HTTP

GET /me/drive/items/{item-id}/children?$expand=thumbnails

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Children.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Expand = new string []{ "thumbnails" };
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

mgc drives items children list --drive-id {drive-id} --drive-item-id {driveItem-id} --expand "thumbnails"

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

requestParameters := &graphdrives.DriveItemItemItemChildrenRequestBuilderGetQueryParameters{
	Expand: [] string {"thumbnails"},
}
configuration := &graphdrives.DriveItemItemItemChildrenRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
children, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Children().Get(context.Background(), configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DriveItemCollectionResponse result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").children().get(requestConfiguration -> {
	requestConfiguration.queryParameters.expand = new String []{"thumbnails"};
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let children = await client.api('/me/drive/items/{item-id}/children')
	.expand('thumbnails')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Children\ChildrenRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new ChildrenRequestBuilderGetRequestConfiguration();
$queryParameters = ChildrenRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->expand = ["thumbnails"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->children()->get($requestConfiguration)->wait();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Files

Get-MgDriveItemChild -DriveId $driveId -DriveItemId $driveItemId -ExpandProperty "thumbnails" 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.children.children_request_builder import ChildrenRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = ChildrenRequestBuilder.ChildrenRequestBuilderGetQueryParameters(
		expand = ["thumbnails"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').children.get(request_configuration = request_configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

The service responses with the list of DriveItems and their thumbnails.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "182331E8-2788-4932-B52A-A6550577043F",
      "name": "my photo.jpg",
      "thumbnails": [
        {
          "small": { "width": 96,
                     "height": 96,
                     "url": "https://sn3302files..."
                   }
        }
      ]
    },
    {
      "id": "2D223953-A56B-4D9B-ADF3-13E7820673A2",
      "name": "presentation.pptx",
      "thumbnails": [
        {
          "small": { "width": 96,
                     "height": 96,
                     "url": "https://sn3302files..."
                   }
        }
      ]
    }
  ]
}

Size options

This table defines the possible thumbnail sizes. While you can request any arbitrary thumbnail size, the defined values are likely to exist and return a value quickly:

Name	Resolution	Aspect Ratio	Description
small	96 longest	Original	Small, highly compressed thumbnail cropped to a square aspect ratio.
medium	176 longest	Original	Cropped to the standard item size for the OneDrive web view.
large	800 longest	Original	Thumbnail with the longest edge resized to 800 pixels.
smallSquare	96x96	Square Crop	Small square thumbnail
mediumSquare	176x176	Square Crop	Small square thumbnail
largeSquare	800x800	Square Crop	Large square thumbnail

Requesting custom thumbnail sizes

In addition to the defined sizes, your app can request a custom thumbnail size by specifying the dimensions of the thumbnail prefixed with c. For example if your app needs thumbnails that are 300x400, it can request that size like this:

HTTP

GET /me/drive/items/{item-id}/thumbnails?select=c300x400_crop

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Thumbnails.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "c300x400_crop" };
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

mgc drives items thumbnails list --drive-id {drive-id} --drive-item-id {driveItem-id}

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

requestParameters := &graphdrives.DriveItemItemItemThumbnailsRequestBuilderGetQueryParameters{
	Select: [] string {"c300x400_crop"},
}
configuration := &graphdrives.DriveItemItemItemThumbnailsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
thumbnails, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Thumbnails().Get(context.Background(), configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ThumbnailSetCollectionResponse result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").thumbnails().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"c300x400_crop"};
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let thumbnails = await client.api('/me/drive/items/{item-id}/thumbnails?select=c300x400_crop')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Thumbnails\ThumbnailsRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new ThumbnailsRequestBuilderGetRequestConfiguration();
$queryParameters = ThumbnailsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["c300x400_crop"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->thumbnails()->get($requestConfiguration)->wait();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Files

Get-MgDriveItemThumbnail -DriveId $driveId -DriveItemId $driveItemId -Property "c300x400_crop" 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.thumbnails.thumbnails_request_builder import ThumbnailsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = ThumbnailsRequestBuilder.ThumbnailsRequestBuilderGetQueryParameters(
		select = ["c300x400_crop"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').thumbnails.get(request_configuration = request_configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Which responds with just the custom thumbnail size selected:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {
      "id": "0",
      "c300x400_crop": { "height": 300, "width": 400, "url": "https://sn3302files.onedrive.com/123"},
    }
  ]
}

You can specify the following options after the size of the thumbnail requested:

Examples of custom identifiers

Thumbnail identifier	Resolution	Aspect ratio	Description
c300x400	Bounded by 300x400 box	Original	Generate a thumbnail that fits inside a 300x400 pixel box, maintaining aspect ratio
c300x400_crop	300x400	Cropped	Generate a thumbnail that is 300x400 pixels. This works by resizing the image to fill the 300x400 box and cropping whatever spills outside the box.

Note: The thumbnail returned may not exactly match the pixel dimensions that was requested, but will match the aspect ratio. In some cases, a larger thumbnail may be returned than was requested, if the thumbnail already exists and can easily be scaled to match the requested resolution.

Remarks

Note In OneDrive for Business and SharePoint:

Using these calls to expand the thumbnails collection will not work:

• GET /drive/root:/{item-path}?expand=children(expand=thumbnails)
• GET /drive/items/{item-id}/children?expand=thumbnails

Thumbnails are not supported on SharePoint Server 2016.

Error responses

See Error Responses for more info about how errors are returned.