# IRPCThumbnails.GetDocumentFileThumbnail

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Thumbnails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetDocumentFileThumbnail/

Badges: `Vault API / standard` `read` `session` `idempotent` `returns metadata structure version`

Gets a classic thumbnail or a first-page preview of one file of an object version, as PNG.

- **Service:** [Thumbnails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/index.md) `MFiles.IRPCThumbnails`
- **gRPC method:** `/MFiles.IRPCThumbnails/GetDocumentFileThumbnail`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-document-file-thumbnail`
- **Request:** [`GetDocumentFileThumbnailRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetDocumentFileThumbnail/index.md#request)
- **Response:** [`GetDocumentFileThumbnailResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetDocumentFileThumbnail/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** read
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session.
- **Classic** (`THUMBNAIL_TYPE_CLASSIC` or `THUMBNAIL_TYPE_CLASSIC_NO_ICON`; the server treats
  them the same): identify the file with a specific file version (`FILE_VER_TYPE_SPECIFIC`). The
  server generates the thumbnail on first request and caches it. Check `thumbnail_status`:
  - `THUMBNAIL_STATUS_GENERATED`: `thumbnail` holds the PNG.
  - `THUMBNAIL_STATUS_CANNOT_GENERATE`: the server has no thumbnail handler for the file type.
  - `THUMBNAIL_STATUS_FAILED_TO_GENERATE`, `THUMBNAIL_STATUS_FAILED_MISSING_DATA_FILE`:
    generation failed, or the file's data is missing.
  - `THUMBNAIL_STATUS_DO_NOT_GENERATE`: thumbnails are turned off, or the file type is excluded
    (see [GetThumbnailOptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetThumbnailOptions/index.md)).
  - `THUMBNAIL_STATUS_NOT_GENERATED`: no thumbnail yet.

  In every case other than `THUMBNAIL_STATUS_GENERATED`, `thumbnail` is empty: show an icon or
  ask for a preview instead.
- **Preview** (`THUMBNAIL_TYPE_PREVIEW`): `obj_ver` must name a specific version
  (`OBJ_VER_VERSION_TYPE_SPECIFIC`); a latest-version reference fails. The file must belong to
  that version. The server renders the first page and scales it to fit within `max_width` x
  `max_height`, keeping the aspect ratio; images are at most 999 pixels on the longer side.
  The response has `thumbnail_type` `THUMBNAIL_TYPE_PREVIEW`. If no preview can be made, the
  response holds the file type's icon instead, with `thumbnail_type` `THUMBNAIL_TYPE_CLASSIC`;
  `thumbnail_status` is `THUMBNAIL_STATUS_GENERATED` in both cases.
- The first preview of a file can take a while, because the server first makes a PDF version
  of the file. Later calls reuse it.
- Previews work only for files stored in the vault; for files of external repositories the
  call fails with "Not implemented.".

<a id="request"></a>

## Request: GetDocumentFileThumbnailRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `obj_ver` | [`ObjVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVer/index.md) | The object version that has the file. For a preview, a specific version. |
| `obj_ver.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object. |
| `obj_ver.obj_id.type` | `int32` | The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID). |
| `obj_ver.obj_id.item_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | The ID of the object within its type, in `item_id.internal_id`. |
| `obj_ver.version` | [`ObjVerVersion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjVerVersion/index.md) | The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`. |
| `obj_ver.version.type` | [`ObjVerVersionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ObjVerVersionType/index.md) | What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number. Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7). |
| `obj_ver.version.internal_version` | `int32` | The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`. |
| `obj_ver.version.external_repository_version` | `string` | Used only for objects in external repositories. Leave empty. |
| `obj_ver.version.external_repository_sort_key` | `int64` | Used only for objects in external repositories. Leave 0. |
| `file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file and its specific version, as in the [File](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) entries of the object version. |
| `file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file_ver.file_id.type` | [`FileIDType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileIDType/index.md) | `FILE_IDTYPE_SPECIFIC` for one file. Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3). |
| `file_ver.file_id.internal_id` | `int32` | The file ID. |
| `file_ver.file_id.external_repository_id` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file_ver.internal_version` | `int32` | The file version number. |
| `file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `type` | [`ThumbnailType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ThumbnailType/index.md) | `THUMBNAIL_TYPE_CLASSIC` (default) for the cached square thumbnail, or `THUMBNAIL_TYPE_PREVIEW` for a first-page preview. Values: `THUMBNAIL_TYPE_CLASSIC` (0), `THUMBNAIL_TYPE_CLASSIC_NO_ICON` (1), `THUMBNAIL_TYPE_PREVIEW` (2). |
| `max_width` | `uint32` | For a preview, the largest width in pixels. Ignored for classic thumbnails. |
| `max_height` | `uint32` | For a preview, the largest height in pixels. Ignored for classic thumbnails. With both `max_width` and `max_height` 0, the server uses a default size. |

<a id="response"></a>

## Response: GetDocumentFileThumbnailResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `thumbnail_status` | [`ThumbnailStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ThumbnailStatus/index.md) | Whether a thumbnail was returned: `THUMBNAIL_STATUS_GENERATED` means `thumbnail` has data. See the remarks for the other values. Values: `THUMBNAIL_STATUS_NO_ACTIONS_ALLOWED` (0), `THUMBNAIL_STATUS_NOT_GENERATED` (1), `THUMBNAIL_STATUS_GENERATED` (2), `THUMBNAIL_STATUS_DO_NOT_GENERATE` (3), `THUMBNAIL_STATUS_CANNOT_GENERATE` (4), `THUMBNAIL_STATUS_FAILED_TO_GENERATE` (5), `THUMBNAIL_STATUS_FAILED_MISSING_DATA_FILE` (6). |
| `thumbnail_type` | [`ThumbnailType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ThumbnailType/index.md) | The kind of image returned: `THUMBNAIL_TYPE_PREVIEW` for a page preview, `THUMBNAIL_TYPE_CLASSIC` for a classic thumbnail or a file type icon. Values: `THUMBNAIL_TYPE_CLASSIC` (0), `THUMBNAIL_TYPE_CLASSIC_NO_ICON` (1), `THUMBNAIL_TYPE_PREVIEW` (2). |
| `thumbnail` | `bytes` | The image as PNG bytes. Empty unless `thumbnail_status` is `THUMBNAIL_STATUS_GENERATED`. |

<a id="related"></a>

## Related methods

- [GetThumbnailOptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnails/GetThumbnailOptions/index.md): Gets the vault's thumbnail settings.