# List all uploads

To retrieve a collection of uploads, send a GET request to the `/uploads` endpoint. The collection is [paginated](https://www.datocms.com/docs/content-management-api/pagination.md), so make sure to iterate over all the pages if you need every record in the collection!

The following table contains the list of all the possible arguments, along with their type, description and examples values.

Pro tip: in case of any doubts you can always inspect the network calls that the CMS interface is doing, as it's using the Content Management API as well!

## Query parameters

**`filter`**

- Type: object

Attributes to filter uploads

<details>
<summary>Show object format</summary>

**`ids`**

- Type: string
- Example: `"12,31"`

IDs to fetch, comma separated

**`query`**

- Type: string
- Example: `"foobar"`

Textual query to match. If `locale` is defined, search within that locale. Otherwise environment's main locale will be used.

**`fields`**

- Type: object
- Example: `{ type: { eq: "image" }, size: { gt: 5000000 } }`

Same as [GraphQL API uploads filters](/docs/content-delivery-api/filtering-uploads). Use snake_case for fields names. If `locale` is defined, search within that locale. Otherwise environment's main locale will be used.

</details>

**`locale`**

- Type: string
- Example: `"it"`

When `filter[query]` or `field[fields]` is defined, filter by this locale. Default: environment's main locale

**`order_by`**

- Type: string
- Example: `"_created_at_DESC,size_ASC"`

Fields used to order results. Format: `<field_name>_<DIRECTION(ASC|DESC)>`. You can pass multiple comma separated rules.

**`page`**

- Type: object

Parameters to control offset-based pagination

<details>
<summary>Show object format</summary>

**`offset`**

- Type: integer
- Example: `200`

The (zero-based) offset of the first entity returned in the collection (defaults to 0)

**`limit`**

- Type: integer

The maximum number of entities to return (defaults to 30, maximum is 500)

</details>

## Returns

Returns an array of resource objects of type [upload](https://www.datocms.com/docs/content-management-api/resources/upload.md)

## Other examples

###### Example Fetching one page of results vs. the whole collection

The `client.uploads.list()` method returns a single page of records, while if you need to iterate over **every** resource in the collection (and not just the first page of results), you can use the `client.uploads.listPagedIterator()` method with an [async iteration statement](https://github.com/tc39/proposal-async-iteration#the-async-iteration-statement-for-await-of), which automatically handles pagination for you.

All the details on how to use `list()` and `listPagedIterator()` are outlined [on this page](https://www.datocms.com/docs/content-management-api/pagination.md#paged-iterators).

```javascript
import { buildClient } from "@datocms/cma-client-node";

async function run() {
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  // iterates over every page of results
  for await (const upload of client.uploads.listPagedIterator()) {
    // Check the 'Returned output' tab for the result ☝️
    console.log(upload);
  }
}

run();
```


###### Example Fetching a filtered list of uploads

You can retrieve a list of uploads filtered by a set of conditions. There are different options and you can combine multiple filters together.

In this example we are filtering by type and size. In particular, we are searching for images bigger than 5MB.

The filtering options are the same as the [GraphQL API uploads filters](https://www.datocms.com/docs/content-delivery-api/filtering-uploads.md). So please check there all the options.

```javascript
import { buildClient } from "@datocms/cma-client-node";

async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  const uploads = await client.uploads.list({
    filter: {
      fields: {
        type: {
          eq: "image",
        },
        size: {
          gt: 5000000,
        },
      },
    },
  });

  console.log(uploads);
}

run();
```

## Related content in "Content Management API"

- [Content Management API Overview](https://www.datocms.com/docs/content-management-api.md)
- [Using the JavaScript CMA client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients.md)
- [API versioning](https://www.datocms.com/docs/content-management-api/api-versioning.md)
- [Authentication](https://www.datocms.com/docs/content-management-api/authentication.md)
- [Environments](https://www.datocms.com/docs/content-management-api/setting-the-environment.md)
- [Error codes & handling failures (CMA)](https://www.datocms.com/docs/content-management-api/errors.md)
- [Pagination](https://www.datocms.com/docs/content-management-api/pagination.md)
- [Asynchronous jobs](https://www.datocms.com/docs/content-management-api/async-jobs.md)
- [CMA Technical Limits & Rate Limits](https://www.datocms.com/docs/content-management-api/technical-limits.md)
- [Record](https://www.datocms.com/docs/content-management-api/resources/item.md)
- [Scheduled publication](https://www.datocms.com/docs/content-management-api/resources/scheduled-publication.md)
- [Scheduled unpublishing](https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing.md)
- [Upload](https://www.datocms.com/docs/content-management-api/resources/upload.md)
- [Create a new upload](https://www.datocms.com/docs/content-management-api/resources/upload/create.md)
- [List all uploads](https://www.datocms.com/docs/content-management-api/resources/upload/instances.md)
- [Retrieve an upload](https://www.datocms.com/docs/content-management-api/resources/upload/self.md)
- [Delete an upload](https://www.datocms.com/docs/content-management-api/resources/upload/destroy.md)
- [Update an upload](https://www.datocms.com/docs/content-management-api/resources/upload/update.md)
- [Referenced records](https://www.datocms.com/docs/content-management-api/resources/upload/references.md)
- [Add tags to assets in bulk](https://www.datocms.com/docs/content-management-api/resources/upload/bulk_tag.md)
- [Put assets into a collection in bulk](https://www.datocms.com/docs/content-management-api/resources/upload/bulk_set_upload_collection.md)
- [Destroy uploads](https://www.datocms.com/docs/content-management-api/resources/upload/bulk_destroy.md)
- [Site](https://www.datocms.com/docs/content-management-api/resources/site.md)
- [Model/Block model](https://www.datocms.com/docs/content-management-api/resources/item-type.md)
- [Field](https://www.datocms.com/docs/content-management-api/resources/field.md)
- [Fieldset](https://www.datocms.com/docs/content-management-api/resources/fieldset.md)
- [Record version](https://www.datocms.com/docs/content-management-api/resources/item-version.md)
- [Upload permission](https://www.datocms.com/docs/content-management-api/resources/upload-request.md)
- [Upload track](https://www.datocms.com/docs/content-management-api/resources/upload-track.md)
- [Manual tags](https://www.datocms.com/docs/content-management-api/resources/upload-tag.md)
- [Smart tags](https://www.datocms.com/docs/content-management-api/resources/upload-smart-tag.md)
- [Upload Collection](https://www.datocms.com/docs/content-management-api/resources/upload-collection.md)
- [Search Index](https://www.datocms.com/docs/content-management-api/resources/search-index.md)
- [Search result](https://www.datocms.com/docs/content-management-api/resources/search-result.md)
- [Search indexing activity](https://www.datocms.com/docs/content-management-api/resources/search-index-event.md)
- [Environment](https://www.datocms.com/docs/content-management-api/resources/environment.md)
- [Maintenance mode](https://www.datocms.com/docs/content-management-api/resources/maintenance-mode.md)
- [Menu Item](https://www.datocms.com/docs/content-management-api/resources/menu-item.md)
- [Schema Menu Item](https://www.datocms.com/docs/content-management-api/resources/schema-menu-item.md)
- [Uploads filter](https://www.datocms.com/docs/content-management-api/resources/upload-filter.md)
- [Model filter](https://www.datocms.com/docs/content-management-api/resources/item-type-filter.md)
- [Plugin](https://www.datocms.com/docs/content-management-api/resources/plugin.md)
- [Workflow](https://www.datocms.com/docs/content-management-api/resources/workflow.md)
- [Asynchronous job](https://www.datocms.com/docs/content-management-api/resources/job.md)
- [Job result](https://www.datocms.com/docs/content-management-api/resources/job-result.md)
- [Account](https://www.datocms.com/docs/content-management-api/resources/account.md)
- [Organization](https://www.datocms.com/docs/content-management-api/resources/organization.md)
- [Invitation](https://www.datocms.com/docs/content-management-api/resources/site-invitation.md)
- [Collaborator](https://www.datocms.com/docs/content-management-api/resources/user.md)
- [Role](https://www.datocms.com/docs/content-management-api/resources/role.md)
- [API token](https://www.datocms.com/docs/content-management-api/resources/access-token.md)
- [Webhook](https://www.datocms.com/docs/content-management-api/resources/webhook.md)
- [Webhook call](https://www.datocms.com/docs/content-management-api/resources/webhook-call.md)
- [Build trigger](https://www.datocms.com/docs/content-management-api/resources/build-trigger.md)
- [Deploy activity](https://www.datocms.com/docs/content-management-api/resources/build-event.md)
- [Subscription limit](https://www.datocms.com/docs/content-management-api/resources/subscription-limit.md)
- [Subscription feature](https://www.datocms.com/docs/content-management-api/resources/subscription-feature.md)
- [SSO Settings](https://www.datocms.com/docs/content-management-api/resources/sso-settings.md)
- [SSO User](https://www.datocms.com/docs/content-management-api/resources/sso-user.md)
- [SSO Group](https://www.datocms.com/docs/content-management-api/resources/sso-group.md)
- [White-label settings](https://www.datocms.com/docs/content-management-api/resources/white-label-settings.md)
- [Audit log event](https://www.datocms.com/docs/content-management-api/resources/audit-log-event.md)