---
sidebar_position: 9
title: list_dives
description: List all Dives in your MotherDuck workspace
feature_stage: preview
---

List all owned [Dives](/docs/key-tasks/ai-and-motherduck/dives) in MotherDuck. Dives are interactive React data apps that query live data. Returns metadata including `current_version` (the latest version number, 1-indexed) for each Dive. Use [`read_dive`](../read-dive) with the optional `version` parameter to retrieve a specific historical version. Optionally filter by keywords to search in title and description.

## Description

The `list_dives` tool returns a list of all Dives in your MotherDuck workspace. Each Dive includes its ID, title, description, owner, version history, and timestamps. Use this to discover existing Dives before reading, updating, or deleting them.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `keywords` | string | No | Keywords to filter dives by title or description (case-insensitive, all words must match) |

## Output Schema

```json
{
  "success": boolean,
  "dives": [                     // Array of dives (on success)
    {
      "id": string,              // Unique identifier (UUID)
      "title": string,           // Dive title
      "description": string,     // Dive description
      "owner_name": string,      // Name of the Dive owner
      "current_version": number, // Latest version number (1-indexed)
      "created_at": string,      // ISO 8601 creation timestamp
      "updated_at": string       // ISO 8601 last update timestamp
    }
  ],
  "count": number,               // Number of dives returned
  "totalCount": number,          // Total number of matching dives
  "truncated": boolean,          // Whether the results were truncated
  "message": string,             // Truncation message (when truncated)
  "error": string                // Error message (on failure)
}
```

## Example Usage

**List all Dives:**

```text
What Dives do I have in my workspace?
```

The AI assistant will call the tool with no parameters.

**Filter Dives by keywords:**

```text
Show me my revenue-related Dives
```

The AI assistant will call the tool with keywords:

```json
{
  "keywords": "revenue"
}
```

**Find a specific Dive to update:**

```text
Show me my existing Dives so I can update the revenue dashboard
```

## Success Response Example

```json
{
  "success": true,
  "dives": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Monthly Revenue Trends",
      "description": "Line chart showing revenue by month with category breakdown",
      "owner_name": "alice",
      "current_version": 3,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-20T14:45:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "title": "Customer Signups by Region",
      "description": "Bar chart of customer signups grouped by region",
      "owner_name": "bob",
      "current_version": 1,
      "created_at": "2025-01-18T09:00:00Z",
      "updated_at": "2025-01-18T09:00:00Z"
    }
  ],
  "count": 2,
  "totalCount": 2
}
```