---
sidebar_position: 7
title: MD_LIST_DIVE_VERSIONS
description: List all versions of a specific Dive with pagination support.
feature_stage: preview
---

Lists all versions of a specific [Dive](/key-tasks/ai-and-motherduck/dives) with pagination support. Each time a Dive's content is updated via [`MD_UPDATE_DIVE_CONTENT`](../md-update-dive-content), a new version is created. This function returns version metadata without the content.

## Syntax

```sql
SELECT * FROM MD_LIST_DIVE_VERSIONS(id = 'your-dive-uuid'::UUID);
SELECT * FROM MD_LIST_DIVE_VERSIONS(
  id = 'your-dive-uuid'::UUID,
  "limit" = 100,
  "offset" = 0
);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `UUID` | Yes | The unique identifier of the Dive |
| `limit` | `UINTEGER` | No | Maximum number of versions to return |
| `offset` | `UINTEGER` | No | Number of versions to skip |

:::tip
`limit` and `offset` are reserved SQL keywords and must be double-quoted when used as named parameters.
:::

## Return Columns

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` | UUID of this version |
| `version` | `UINTEGER` | Version number (0-based) |
| `storage_url` | `VARCHAR` | Storage URL of the version content |
| `description` | `VARCHAR` | Version description or commit message |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When this version was created |
| `api_version` | `UINTEGER` | API version used to create this version |

## Examples

List all versions of a Dive:

```sql
SELECT version, description, created_at
FROM MD_LIST_DIVE_VERSIONS(id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'::UUID);
```

Get the 5 most recent versions:

```sql
SELECT version, description, created_at
FROM MD_LIST_DIVE_VERSIONS(id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'::UUID)
ORDER BY version DESC
LIMIT 5;
```

## Errors

Returns an error if the Dive does not exist.

## Related

- [`MD_GET_DIVE_VERSION`](../md-get-dive-version) — Retrieve a specific version including content
- [`MD_UPDATE_DIVE_CONTENT`](../md-update-dive-content) — Create a new version