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

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# dataset.listItems()

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

Lists items in the dataset. When a `version` is specified, returns all items at that version. Otherwise, returns paginated items from the latest version.

## 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 })

// List all items at a specific version
const versionedItems = await dataset.listItems({ version: 2 })
```

## Parameters

**version** (`number`): Dataset version to list items at. When set, returns all items at that version (no pagination).

**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 `version` is specified:

**result** (`Promise<DatasetItem[]>`): Array of all items at the specified dataset version.

When `version` isn't specified:

**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.