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

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.

object

items:

DatasetItem[]

Array of items for the current page.

pagination:

object

Pagination metadata.

object

total:

number

Total number of items.

page:

number

Current page number.

perPage:

number | false

Items per page, or false if unpaginated.

hasMore:

boolean

Whether more pages are available.