author	spgraph-docs-team
description	Retrieve a collection of thumbnailSet resources for a driveItem resource.
ms.date	09/10/2017
title	List thumbnails for a driveItem
ms.localizationpriority	medium
ms.subservice	sharepoint
doc_type	apiPageType

List thumbnails for a driveItem

Namespace: microsoft.graph

[!INCLUDE beta-disclaimer]

Retrieve a collection of thumbnailSet resources for a driveItem resource.

Zero or more thumbnailSet resources can represent a driveItem. 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're 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

[!INCLUDE national-cloud-support]

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.

[!INCLUDE permissions-table]

[!INCLUDE app-permissions]

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. It is currently only supported on OneDrive Personal.

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 that retrieves available thumbnails for an item in the current user's OneDrive.

HTTP

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

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

It 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

The following example shows the 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#

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

Go

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

Java

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

Python

[!INCLUDE snippet-not-available] [!INCLUDE 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's a custom thumbnail, its index is 0.
size	string	The size of the thumbnail requested. It 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#

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

Go

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

Java

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

Python

[!INCLUDE snippet-not-available] [!INCLUDE 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 changes, if the item changes in a way that requires a new thumbnail to be generated.

Getting thumbnails while listing driveItems

If you're retrieving a list of driveItem resources to display, you can use the $expand query string parameter to also include the thumbnails for those resources. It 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#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE 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 values

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#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE 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. It 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 were requested, but does 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 doesn't work:

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

Thumbnails aren't supported on SharePoint Server 2016.

Error responses

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

FilesExpand file tree

driveitem-list-thumbnails.md

Latest commit

History

driveitem-list-thumbnails.md

File metadata and controls

List thumbnails for a driveItem

Permissions

HTTP request

Optional query parameters

Response

Example

Response

Get a single thumbnail

HTTP request

Path parameters

Retrieve thumbnail binary content

HTTP request

Response

Getting thumbnails while listing driveItems

HTTP request

Response

Size values

Requesting custom thumbnail sizes

Examples of custom identifiers

Remarks

Error responses