# getPiecesWithMetadata

> **getPiecesWithMetadata**(`client`, `options`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`OutputType`](/reference/filoz/synapse-core/pdp-verifier/namespaces/getpieceswithmetadata/type-aliases/outputtype/)\>

Defined in: [packages/synapse-core/src/pdp-verifier/get-pieces.ts:191](https://github.com/FilOzone/synapse-sdk/blob/aaa98045b003ec23f4318ba9a3032a434e5a20c9/packages/synapse-core/src/pdp-verifier/get-pieces.ts#L191)

Get one bounded page of visible pieces and their metadata.

The source cursor is preserved when scheduled-removal filtering produces
fewer or no visible items. Treat `nextCursor` as opaque and use
[paginate](/reference/filoz/synapse-core/core/functions/paginate/) to traverse every page.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `client` | `Client`\<`Transport`, `Chain`\> | The client to use to get the pieces with metadata. |
| `options` | \{ `address`: `` `0x${string}` ``; `contractAddress?`: `` `0x${string}` ``; `cursor?`: `bigint`; `dataSet`: [`PdpDataSet`](/reference/filoz/synapse-core/warm-storage/interfaces/pdpdataset/); `limit?`: `bigint`; \} | [getPiecesWithMetadata.OptionsType](/reference/filoz/synapse-core/pdp-verifier/namespaces/getpieceswithmetadata/type-aliases/optionstype/) |
| `options.address` | `` `0x${string}` `` | The address of the user. |
| `options.contractAddress?` | `` `0x${string}` `` | Optional PDPVerifier contract address override. |
| `options.cursor?` | `bigint` | Opaque continuation cursor returned by the previous page. Defaults to `0n`. |
| `options.dataSet` | [`PdpDataSet`](/reference/filoz/synapse-core/warm-storage/interfaces/pdpdataset/) | The data set to get the pieces from. |
| `options.limit?` | `bigint` | Maximum number of items to return. Must be greater than `0n`. |

## Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`OutputType`](/reference/filoz/synapse-core/pdp-verifier/namespaces/getpieceswithmetadata/type-aliases/outputtype/)\>

The active pieces for the data set [getPiecesWithMetadata.OutputType](/reference/filoz/synapse-core/pdp-verifier/namespaces/getpieceswithmetadata/type-aliases/outputtype/)

## Examples

**Read the first page**

```ts
import { getPiecesWithMetadata } from '@filoz/synapse-core/pdp-verifier'
import { calibration } from '@filoz/synapse-core/chains'
import { createPublicClient, http } from 'viem'

const client = createPublicClient({
  chain: calibration,
  transport: http(),
})

const address = '0x0000000000000000000000000000000000000000'
const page = await getPiecesWithMetadata(client, { dataSet, address })
console.log(page.items, page.nextCursor)
```

**Iterate over every page**

```ts
import { paginate } from '@filoz/synapse-core'
import { getPiecesWithMetadata } from '@filoz/synapse-core/pdp-verifier'

for await (const piece of paginate(({ cursor }) =>
  getPiecesWithMetadata(client, { dataSet, address, cursor })
)) {
  console.log(piece.id, piece.metadata)
}
```

## Throws

Errors [getPiecesWithMetadata.ErrorType](/reference/filoz/synapse-core/pdp-verifier/namespaces/getpieceswithmetadata/type-aliases/errortype/)