> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# File group operations

> Uploadcare features a powerful CDN that can deliver your content across the world in no time.

File groups serve as collections of files that help you organize
content within your Uploadcare project. Most often, groups of files
are used in [multipage document conversion](/docs/transformations/file-conversion/#multipage-conversion)
and creating [video thumbnails](/docs/transformations/video-encoding/#operation-thumbs).
The files after applying these operations are marked as a group
and you can access them.

You can access file group via `:group_uuid`:

[`https://:subdomain.ucarecd.net/:group_uuid/`](https://examples.ucarecd.net/cd334b26-c641-4393-bcce-b5041546430d~11/)

`:subdomain` is your project's subdomain. Find it in [Delivery](https://app.uploadcare.com/projects/-/settings/#delivery).

`:group_uuid` is similar to a single file UUID but contains the file number
`~N` at the end.

A group URL refers to a page listing individual file URLs with their UUIDs
and index numbers in that group.

File group limitations:

* File groups can contain up to 1000 files.
* File groups are immutable; adding, deleting or changing group elements is impossible.
* A group itself and files within it MUST belong to the same project.

## Creating file groups

One of the other typical use cases is creating a file group when a user
uploads multiple files simultaneously and then wants to display them together.

You can create a group of already uploaded files:

```bash
curl -L 'https://upload.uploadcare.com/group/' \
     -F 'pub_key="$YOUR_PUBLIC_KEY"' \
     -F 'files[0]=":uuid1"' \
     -F 'files[1]=":uuid2/-/scale_crop/400x600/"' \
     -F 'files[2]=":uuid3"'
```

Get `$YOUR_PUBLIC_KEY` from [API keys](https://app.uploadcare.com/projects/-/api-keys/).

Check out our API refs for [creating](https://uploadcare.com/docs/api/upload/groups/create-files-group) and
[managing](https://uploadcare.com/docs/api/rest/group/groups-list) groups.

### Creating file groups via File Uploader

When uploading multiple files via a [File Uploader](/docs/file-uploader/),
you can group them and assign them the same URL. This option is turned off
by default. When it's turned on, it stores UUIDs of uploaded files.
In this case, a separate URL is also generated for each file.

## Getting file group information

You can get information about a file group:

```bash
curl -L 'https://upload.uploadcare.com/group/info/?pub_key=$YOUR_PUBLIC_KEY&group_id=group_uuid'
```

Returns a JSON object with information about a file group
(when the group was created, number of the files in the group, etc).

## Accessing a single file in a group

Requesting a specific file in a group is achieved by adding `/nth/i/`,
where `i` is a file index, starting from 0:

[`/:group_uuid/nth/0/`](https://examples.ucarecd.net/cd334b26-c641-4393-bcce-b5041546430d~11/nth/0/)

[`/:group_uuid/nth/1/`](https://examples.ucarecd.net/cd334b26-c641-4393-bcce-b5041546430d~11/nth/1/)

[`/:group_uuid/nth/2/`](https://examples.ucarecd.net/cd334b26-c641-4393-bcce-b5041546430d~11/nth/2/)

Note, there is no `/-/` separator after a group UUID.
It's required for image processing operations only.

## Applying image processing operations

Image processing operations cannot be applied to a file group URL.

You can group several files with image processing operations already applied.
In this case, the transform file can be requested directly as a group element (/nth/N/).

[`/:group_uuid/nth/1/`](https://examples.ucarecd.net/cd334b26-c641-4393-bcce-b5041546430d~11/nth/1//)

Adding additional processing operations after `/-/` will apply them on top of the
existing ones. You can apply [image processing operations](/docs/transformations/image/#image-transformations-list)
to individual files within a group:

[`/:group_uuid/nth/1/-/resize/256x/`](https://examples.ucarecd.net/cd334b26-c641-4393-bcce-b5041546430d~11/nth/1/-/resize/256x/)

## Getting a group as an archive \[#get-as-archive]

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

The operation limits are:

* A total size of uncompressed files ≤ 2 GB.
* Processing operations will be discarded.\

  Only original files will be archived.\


Note: If you add an image with a transformation to a group, then only the
original images will be loaded when exporting the archive of this group.

Here's how to get an archived file group:

```
/:group_uuid/archive/:format/:filename
```

Where:

* `: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 archive filename.

Note: If the group contains a removed file, the archive operation will fail with
a 404 error code.

## Deleting groups

Deleting a file group using the REST API deletes only the group object itself.
All files included in the group will remain intact.

You can delete a group:

```bash
curl -L 'https://api.uploadcare.com/groups/:group_uuid/' \
     -X DELETE \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/vnd.uploadcare-v0.7+json' \
     -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY"
```

Get `$YOUR_PUBLIC_KEY` and `$YOUR_SECRET_KEY` from [API keys](https://app.uploadcare.com/projects/-/api-keys/).

Note: Cleaning the CDN cache may take some time after deletion.

For more information on managing file groups,
refer to the [REST API references](https://uploadcare.com/docs/api/rest/group/groups-list).