@mastra/core/dist/docs/references/reference-datasets-list.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# DatasetsManager.list()

**Added in:** `@mastra/core@1.4.0`

Lists datasets with pagination and optional filters. Filters are applied at the storage layer, so callers don't need to post-filter results.

## Usage example

```typescript
import { Mastra } from '@mastra/core'

const mastra = new Mastra({
  /* storage config */
})

const { datasets, pagination } = await mastra.datasets.list({ page: 0, perPage: 10 })

for (const ds of datasets) {
  console.log(`${ds.id}: ${ds.name} (v${ds.version})`)
}

// Filter by target type and name (case-insensitive substring)
const filtered = await mastra.datasets.list({
  page: 0,
  perPage: 20,
  filters: { targetType: 'agent', name: 'qa' },
})

// Filter by any-overlap match on target IDs
const forAgents = await mastra.datasets.list({
  filters: { targetIds: ['agent-a', 'agent-b'] },
})
```

## Parameters

**page** (`number`): Page number. Defaults to 0.

**perPage** (`number`): Number of datasets per page. Defaults to 20.

**filters** (`object`): Optional filters applied at the storage layer.

**filters.organizationId** (`string`): Tenancy filter: restrict to datasets in this organization.

**filters.projectId** (`string`): Tenancy filter: restrict to datasets in this project.

**filters.candidateKey** (`string`): Restrict to datasets belonging to this candidate key.

**filters.candidateId** (`string`): Restrict to datasets belonging to this candidate ID.

**filters.targetType** (`'agent' | 'workflow' | 'scorer' | 'processor'`): Restrict to datasets targeting this component type.

**filters.targetIds** (`string[]`): Restrict to datasets whose targetIds intersect this list (any-overlap match). Empty array is treated as no filter.

**filters.name** (`string`): Case-insensitive substring match on dataset name. Empty string is treated as no filter.

## Returns

**result** (`Promise<object>`): Paginated dataset list.

**result.datasets** (`DatasetRecord[]`): Array of dataset records. See dataset.getDetails() for the record shape.

**result.pagination** (`PaginationInfo`): Pagination metadata with total, page, perPage, and hasMore.