What a group is

Groups are file collections. You can use those to organize content in your Uploadcare project. The advised use case for groups is using them in single content upload or delivery transactions. For instance, each time you use multi-upload with our widget, a new group holding UUIDs of uploaded files is created. You can access file collections via :group_uuid. Here is an example,

:group_uuid is similar to file UUIDs with the only difference of having ~N at the end, where N stands for a number of files in a group. The maximum group file limit is 1000. We set the limit to ensure your app would optimally perform and interact with our API.

Navigating through a URL holding group UUID will result in getting a list of individual UUIDs of files in that group. Groups serve the purpose of organizing files in your projects. For instance, every multi-file upload via our widget makes a new group. You can still access every single file in your group.

Technically, our widget creates a file group on multi-upload using Uploadcare APIs. Learn more about creating and managing groups.

Accessing single files in a group

When working with groups, you can request a single file by using its zero-based index,


Note, there is no /-/ separator after a group UUID: the /nth/ URL directive does not belong to Image Transformations. Each group UUID includes a number of files in this group so you could iterate through them. Files in a group still have support for Image Transformations,


You can also make groups from processed files. Such files are added together with the respective sequences of operations. So, if you request a file from a group, it is invoked with all the stored operations. Adding more controls to such files will combine them with the existing ones.

Get group as archive

Getting a group as an archive is technically done via the archive group processing operation.

Current operation limits are:

  • A total size of uncompressed files in a group should not exceed 2 GB.
  • Any URL directives related to processing operations are discarded within a group are discarded: only original file versions are added to the output archive.

The workflow of getting an archived file group is straight-forward:

  • :group_uuid — UUID of a file group you want to get as an archive.
  • :format — the format of that output archive, we support zip and tar.
  • :filename — (optional) output filename: you can either specify a name for your archive or omit the parameter; more about filenames here.

A gallery is a way to render a group of images to a single page. The gallery feature is powered by the Fotorama JavaScript library.

Making a gallery is also based on a group processing operation, gallery. Here’s how it works,


You can customize the layout and behavior of images in a gallery by adding Fotorama options to their URLs. The workflow is pretty much the same as with our Image Transformations except that we do not support image size, dimensions, and ratio manipulations here.


One of great use cases with gallery is embedding a collection of images right into your page via <iframe>,