author	spgraph-docs-team
ms.date	09/10/2017
title	Retrieve thumbnails for a file or folder
ms.localizationpriority	medium
ms.subservice	sharepoint
description	Retrieve a collection of ThumbnailSet resources for a DriveItem resource.
doc_type	apiPageType

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

[!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. 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.

Examples

Example 1: Retrieve available thumbnails for an item in the current user's OneDrive

Request

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#

[!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]

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..."}
    }
  ]
}

Example 2: Get a single thumbnail

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

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 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.

Response#

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

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

Example 3: Retrieve thumbnail binary content

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

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 will change, if the item changes in a way that requires a new thumbnail to be generated.

Example 4: 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.

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..."
                   }
        }
      ]
    }
  ]
}

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

Example 5: 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:

Request

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]

Response

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.

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

Request headers

Response

Examples

Example 1: Retrieve available thumbnails for an item in the current user's OneDrive

Request

Response

Example 2: Get a single thumbnail

Request

Path parameters

Response#

Example 3: Retrieve thumbnail binary content

Request

Response

Example 4: Getting thumbnails while listing DriveItems

Request

Response

Example 5: Requesting custom thumbnail sizes

Request

Response

Examples of custom identifiers

Remarks

Error responses