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

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

# dataset.listItems()

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

Lists items in the dataset. When only `version` is provided, returns a bare `DatasetItem[]` snapshot of every item at that version. In all other cases — no arguments, or `search` / `page` / `perPage` provided with or without `version` — returns a paginated `{ items, pagination }` shape.

## Usage example

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

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

const dataset = await mastra.datasets.get({ id: 'dataset-id' })

// Paginated list (default: page 0, 20 per page)
const result = await dataset.listItems()

// List with search
const filtered = await dataset.listItems({ search: 'TypeScript', page: 0, perPage: 10 })

// Paginated list scoped to a specific version
const versionedPage = await dataset.listItems({ version: 2, page: 0, perPage: 20 })

// Version-only snapshot returns a bare DatasetItem[] (deprecated form —
// prefer passing page/perPage to receive the paginated shape).
const versionedItems = await dataset.listItems({ version: 2 })
```

## Parameters

**version** (`number`): Dataset version to list items at. When passed on its own, returns every item at that version as a bare DatasetItem\[] snapshot. Passing search / page / perPage alongside version switches to the paginated shape.

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

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

**search** (`string`): Search string to filter items.

## Returns

When only `version` is provided (no `search`, `page`, or `perPage`):

**result** (`Promise<DatasetItem[]>`): Bare array of every item at the specified dataset version. This shape is retained for backwards compatibility and is deprecated — pass page / perPage (or search) to always receive the paginated shape below.

In all other cases (no arguments, or `search` / `page` / `perPage` provided with or without `version`):

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

**result.items** (`DatasetItem[]`): Array of items for the current page.

**result.pagination** (`object`): Pagination metadata.

**result.pagination.total** (`number`): Total number of items.

**result.pagination.page** (`number`): Current page number.

**result.pagination.perPage** (`number | false`): Items per page, or false if unpaginated.

**result.pagination.hasMore** (`boolean`): Whether more pages are available.