Skip to navigation

Get Metadata Async

Preview
View as Markdown

Asynchronous file metadata extraction for supported file formats. The kind of metadata returned depends on the file type:

  • Image (EXIF) formats: .3fr, .arw, .avif, .bmp, .cr2, .cr3, .crw, .dcr, .dcs, .dng, .erf, .gif, .heic, .j2c, .j2k, .jp2, .jpc, .jpeg, .jpf, .jpg, .jpg2, .jpm, .jpx, .kdc, .mef, .mos, .mrw, .nef, .nrw, .orf, .pef, .png, .ppm, .r3d, .raf, .rw2, .rwl, .sr2, .tga, .tif, .tiff, .wbmp, .web, .webp, .x3f.
  • Audio/video (media) formats: .aac, .aif, .aiff, .flac, .m4a, .m4r, .mp3, .oga, .ogg, .wav, .wma, .3gp, .3gpp, .3gpp2, .asf, .avi, .dv, .flv, .m2t, .m2ts, .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .mts, .mxf, .oggtheora, .ogv, .rm, .ts, .vob, .webm, .wmv.
  • PDF format: .pdf.
  • MS Office formats: .docx, .pptx, .xlsx.

Files in other formats fail with MetadataExtractionApiV2Error.user_error.

Size limits depend on the kind of metadata being extracted: at most 200 MB for image (EXIF) files, 100 GB for audio/video files, 500 MB for PDFs, and 288 MB for MS Office files. Files over the limit for their kind fail with MetadataExtractionApiV2Error.user_error.

The metadata is not returned by this route. Poll get_metadata_async/check with the returned async job ID until it reports GetMetadataAsyncCheckResult.complete or GetMetadataAsyncCheckResult.failed.

Required scope: files.content.read

Endpoint format: RPC

Authentication: App, User

This endpoint does not support apps with the app folder permission.

Authentication

AuthorizationBearer

App-level OAuth 2.0 token (no user context). Use Authorization: Bearer <token>.

Obtain by calling the token endpoint with grant_type=client_credentials.

Only available on endpoints that declare app auth support.

OR
AuthorizationBearer

OAuth 2.0 token issued to a specific user. Use Authorization: Bearer <token>.

Public clients should use the authorization code flow with PKCE (S256).

For background or offline access, send token_access_type=offline during authorization and use the returned refresh token to obtain new access tokens.

You can generate a short-lived access token in the Developer Console; see Testing with a generated token.

Headers

Dropbox-API-Select-UserstringOptional

Acts on behalf of a team member for supported user-auth operations. Pass a team member ID such as dbmid:.... When used with a team token, that token must also include the team_data.member scope.

Dropbox-API-Path-RootstringOptional

Scopes path-based operations to a namespace (root). The value is a JSON serialization of the common.PathRoot union: {".tag": "home"}, {".tag": "root", "root": "<namespace_id>"}, or {".tag": "namespace_id", "namespace_id": "<namespace_id>"}. On failure the request returns 422 with a common.PathRootError.

Request

This endpoint expects a nullable object.
file_id_or_urlobject or nullOptional

Identifier of the file to extract metadata from. Callers must set exactly one of the FileIdOrUrl variants. The kind of metadata returned is determined by the file type: image files return EXIF metadata, audio/video files return media metadata, PDFs return PDF metadata, and MS Office documents (docx, pptx, xlsx) return Office metadata. See the route description for the supported formats. Requests against unsupported formats fail with MetadataExtractionApiV2Error.user_error.

Variant:
riviera_api_v2.FileIdOrUrl.file_idobjectRequired

A Dropbox-issued file ID for a file the authenticated user has access to, e.g. “id:a4ayc_80_OEAAAAAAAAAYa”.

Response headers

X-Dropbox-Request-IdstringOptional
A unique identifier for the request, useful for debugging and support.

Response

Successful response
Variant:
async_common.LaunchResultBase.async_job_idobject
This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.

Errors

401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error