---
sidebar_position: 2
title: list_shares
description: List database shares that have been shared with you
---

# list_shares

List all database [shares](/key-tasks/sharing-data/sharing-overview) that have been shared with you.

## Description

The `list_shares` tool returns all database shares that have been shared with you by other users. Each share includes its name and URL, which can be used to attach the share as a database using the `query` tool.

To attach a share, execute: `ATTACH '<share_url>' AS my_alias;`

To detach a share: `DETACH <database_alias>;`

## Input Parameters

This tool takes no input parameters.

## Output Schema

```json
{
  "success": boolean,
  "shares": [                    // List of shares (on success)
    {
      "name": string,            // Share name
      "url": string              // Share URL for attaching
    }
  ],
  "error": string                // Error message (on failure)
}
```

## Example Usage

**List available shares:**

```text
What shares have been shared with me?
```

The AI assistant will call the tool with no parameters.

**Attach a share after listing:**

```text
Attach the sales_data share so I can query it
```

After getting the share URL from `list_shares`, the AI will use the `query` tool:

```json
{
  "database": "my_db",
  "sql": "ATTACH 'md:_share/org123/sales_data' AS sales_data"
}
```

## Success Response Example

```json
{
  "success": true,
  "shares": [
    {
      "name": "sales_data",
      "url": "md:_share/org123/sales_data"
    },
    {
      "name": "product_catalog",
      "url": "md:_share/org456/product_catalog"
    },
    {
      "name": "analytics_benchmark",
      "url": "md:_share/org789/analytics_benchmark"
    }
  ]
}
```

## Empty Response Example

When no shares have been shared with you:

```json
{
  "success": true,
  "shares": []
}
```

## Related

- [Sharing Overview](/key-tasks/sharing-data/sharing-overview) - Learn about MotherDuck's data sharing capabilities
- [Managing Shares](/key-tasks/sharing-data/managing-shares) - How to create and manage shares