---
title: "List file version retentions"
method: GET
path: "/file_version_retentions"
tags: ["File version retentions"]
---

# List file version retentions

`GET /file_version_retentions`

Retrieves all file version retentions for the given enterprise.

**Note**:
File retention API is now **deprecated**.
To get information about files and file versions under retention,
see [files under retention](https://developer.box.com/reference/get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](https://developer.box.com/reference/get-retention-policy-assignments-id-file-versions-under-retention) endpoints.

## Query parameters

- `file_id` string
- `file_version_id` string
- `policy_id` string
- `disposition_action` 'permanently_delete' | 'remove_retention'
- `disposition_before` string
- `disposition_after` string
- `limit` integer
- `marker` string

## Response `200`

Returns a list of all file version retentions for the enterprise.

- FileVersionRetentions — The part of an API response that describes marker based pagination.
  - `limit` integer — The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.
  - `next_marker` string, nullable — The marker for the start of the next page of results.
  - `prev_marker` string, nullable — The marker for the start of the previous page of results.
  - `entries` FileVersionRetention[] — A list of file version retentions.
    - `id` string — The unique identifier for this file version retention.
    - `type` 'file_version_retention' — The value will always be `file_version_retention`.
    - `file_version` object — The file version this file version retention was applied to.
      - `id` string, required — The unique identifier that represent a file version.
      - `type` 'file_version', required — The value will always be `file_version`.
      - `sha1` string — The SHA1 hash of this version of the file.
    - `file` object, nullable — The file this file version retention was applied to.
      - `id` string, required — The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.
      - `etag` string, nullable — The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened.
      - `type` 'file', required — The value will always be `file`.
      - `sequence_id` string — A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.
      - `name` string — The name of the file.
      - `sha1` string, digest — The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
      - `file_version` object — The information about the current version of the file.
        - `id` string, required — The unique identifier that represent a file version.
        - `type` 'file_version', required — The value will always be `file_version`.
        - `sha1` string — The SHA1 hash of this version of the file.
    - `applied_at` string, date-time — When this file version retention object was created.
    - `disposition_at` string, date-time — When the retention expires on this file version retention.
    - `winning_retention_policy` object — The winning retention policy applied to this file version retention. A file version can have multiple retention policies applied.
      - `id` string, required — The unique identifier that represents a retention policy.
      - `type` 'retention_policy', required — The value will always be `retention_policy`.
      - `policy_name` string — The name given to the retention policy.
      - `retention_length` string, int32 — The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`.
      - `disposition_action` 'permanently_delete' | 'remove_retention' — The disposition action of the retention policy. This action can be `permanently_delete`, which will cause the content retained by the policy to be permanently deleted, or `remove_retention`, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired.
      - `max_extension_length` union — The maximum extension length of the retention date. This value specifies the duration in days for which the retention date of the file under policy can be extended. If the policy type is other than 'finite' or the disposition action is other than 'permanently delete', or the maximum extension length is undefined, this field will be set to 'none'.
        - 'none'
        - string, int32

## Other responses

- `default` — An unexpected client error.

---

[API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)