Box Developer Documentation
Log in

Get metadata on item

Guides Metadata Metadata instances Get metadata on item
Edit this page

Get metadata on item

Information about an instance of a metadata template assigned to a file or folder can be retrieved using the item's id, and the template's templateKey and scope.

Metadata scopes can be either global for templates available to all enterprises, enterprise for templates available to the current enterprise, or the enterprise_:id for templates belonging to an enterprise whose ID is the :id value in the scope name.

Get metadata instance on file

To get an instance of a metadata template on a file, call the GET /files/:file_id/metadata/:scope/:templateKey API endpoint with the file's file_id and the template's scope and templateKey.

cURL
curl -i -X GET "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \
     -H "authorization: Bearer <ACCESS_TOKEN>"
TypeScript Gen
await client.fileMetadata.getFileMetadataById(
  file.id,
  'global' as GetFileMetadataByIdScope,
  'properties',
);
Python Gen
client.file_metadata.get_file_metadata_by_id(
    file.id, GetFileMetadataByIdScope.GLOBAL, "properties"
)
.NET Gen
await client.FileMetadata.GetFileMetadataByIdAsync(fileId: file.Id, scope: GetFileMetadataByIdScope.Global, templateKey: "properties");
Java
// Get the default free-form metadata properties
BoxFile file = new BoxFile(api, "id");
Metadata metadata = file.getMetadata();

// Unknown type metadata field, you can test for type or try to get as any type
JsonValue unknownValue = metadata.getValue("/someField");

// String or Enum metadata fields
String stringValue = metadata.getString("/author");

// Float metadata fields can be interpreted as any numeric type
float floatValue = metadata.getFloat("/price");

// Date metadata fields
Date dateValue = metadata.getDate("/deadline");

// Multiselect metadata fields
List<String> multiSelectValues = metadata.getMultiSelect("/categories");
Python
metadata = client.file(file_id='11111').metadata(scope='enterprise', template='myMetadata').get()
print(f'Got metadata instance {metadata["$id"]}')
.NET
Dictionary<string, object> metadata = await client.MetadataManager.
    .GetFileMetadataAsync(fileId: "11111", "enterprise", "marketingCollateral");
Node
client.files.getMetadata('11111', client.metadata.scopes.ENTERPRISE, 'marketingCollateral')
	.then(metadata => {
		/* metadata -> {
			audience: 'internal',
			documentType: 'Q1 plans',
			competitiveDocument: 'no',
			status: 'active',
			author: 'Jones',
			currentState: 'proposal',
			'$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
			'$parent': 'file_11111',
			'$id': '2094c584-68e1-475c-a581-534a4609594e',
			'$version': 0,
			'$typeVersion': 0,
			'$template': 'marketingCollateral',
			'$scope': 'enterprise_12345' }
		*/
	});
iOS
client.metadata.get(
    forFileWithId: "11111",
    scope: "enterprise",
    templateKey: "personnelRecord"
) { (result: Result<MetadataObject, BoxSDKError>) in
    guard case let .success(metadata) = result {
        print("Error retrieving metadata")
        return
    }

    print("Found personnel record for \(metadata.keys["name"])")
}

To get the scope and templateKey for a template, either list all metadata templates, or list all instances on an file.

Get metadata instance on folder

To get an instance of a metadata template on a folder, call the GET /folders/:folder_id/metadata/:scope/:templateKey API endpoint with the folder's folder_id and the template's scope and templateKey.

cURL
curl -i -X GET "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \
     -H "authorization: Bearer <ACCESS_TOKEN>"
TypeScript Gen
await client.folderMetadata.getFolderMetadataById(
  folder.id,
  'global' as GetFolderMetadataByIdScope,
  'properties',
);
Python Gen
client.folder_metadata.get_folder_metadata_by_id(
    folder.id, GetFolderMetadataByIdScope.GLOBAL, "properties"
)
.NET Gen
await client.FolderMetadata.GetFolderMetadataByIdAsync(folderId: folder.Id, scope: GetFolderMetadataByIdScope.Global, templateKey: "properties");
Java
BoxFolder folder = new BoxFolder(api, "id");
Metadata metadata = folder.getMetadata();

// Unknown type metadata field, you can test for type or try to get as any type
JsonValue unknownValue = metadata.getValue("/someField");

// String or Enum metadata fields
String stringValue = metadata.getString("/author");

// Float metadata fields can be interpreted as any numeric type
float floatValue = metadata.getFloat("/price");

// Date metadata fields
Date dateValue = metadata.getDate("/deadline");
Python
metadata = client.folder(folder_id='22222').metadata(scope='enterprise', template='myMetadata').get()
print(f'Got metadata instance {metadata["$id"]}')
.NET
Dictionary<string, object> metadata = await client.MetadataManager.
    .GetFolderMetadataAsync(folderId: "11111", "enterprise", "marketingCollateral");
Node
client.folders.getMetadata('11111', client.metadata.scopes.ENTERPRISE, 'marketingCollateral')
	.then(metadata => {
		/* metadata -> {
			audience: 'internal',
			documentType: 'Q1 plans',
			competitiveDocument: 'no',
			status: 'active',
			author: 'Jones',
			currentState: 'proposal',
			'$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
			'$parent': 'folder_11111',
			'$id': '2094c584-68e1-475c-a581-534a4609594e',
			'$version': 0,
			'$typeVersion': 0,
			'$template': 'marketingCollateral',
			'$scope': 'enterprise_12345' }
		*/
	});
iOS
client.metadata.get(
    forFolderWithId: "22222",
    scope: "enterprise",
    templateKey: "personnelRecord"
) { (result: Result<MetadataObject, BoxSDKError>) in
    guard case let .success(metadata) = result {
        print("Error retrieving metadata")
        return
    }

    print("Found personnel record for \(metadata.keys["name"])")
}

To get the scope and templateKey for a template, either list all metadata templates, or list all instances on an folder.