# List Dataset Data Items

> Paginate through data chunks within a dataset collection with keyword search across question/answer fields and image URLs.

Source: https://doc.fastgpt.io/openapi/reference/dataset-data/v2-list
Last Updated: 2026-11-18

## Endpoint Overview

* **Method** : `POST`
* **Path** : `/api/core/dataset/data/v2/list`
* **Module** : Datasets / Dataset Data
* **Authentication** : `Authorization: Bearer <apiKey>`—Personal API Key (access scoped by team member permissions) (see [API Getting Started](https://doc.fastgpt.io/openapi/intro) )
* **Interactive Try-It-Out** : [Open in Scalar API Explorer](https://cloud.fastgpt.io/apidoc/systemopenapi#tag/%E6%95%B0%E6%8D%AE%E7%AE%A1%E7%90%86/POST/core/dataset/data/v2/list) (self-hosted instances: replace the origin with `<instance>/apidoc/systemopenapi#tag/%E6%95%B0%E6%8D%AE%E7%AE%A1%E7%90%86/POST/core/dataset/data/v2/list` )

## Description & Notes

Query paginated data items inside a collection with keyword search and signed image preview URLs.

## Request Parameters

### Request Body ( `application/json` )

#### Shared Parameters Across Branches

| Field          | Type     | Required | Default | Constraints & Description                   |
| -------------- | -------- | -------- | ------- | ------------------------------------------- |
| `collectionId` | `string` | Yes      | -       | Collection ID. pattern: `^[0-9a-fA-F]{24}$` |
| `searchText`   | `string` | No       | -       | Search keyword matching `q` and `a` fields  |

**Mutually Exclusive Branches ( `anyOf` )**

* **Offset Pagination**

Specify the 0-based starting offset; when both `offset` and `pageNum` are provided, `offset` takes precedence.

| Field      | Type      | Required | Default | Constraints & Description                                                                                                                        |
| ---------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `offset`   | `integer` | Yes      | -       | **Mutually Exclusive Group: Pagination Parameters** . 0-based offset. min: 0; max: 9007199254740991                                              |
| `pageSize` | `integer` | No       | `20`    | **Mutually Exclusive Group: Pagination Parameters** . Items per page. Defaults to 20, capped at 500 (larger values are clamped to 500). max: 500 |

* **Page-Number Pagination**

Paginate by page number (starts at page 1); `pageSize` controls items per page.

| Field      | Type      | Required | Default | Constraints & Description                                                                                                                        |
| ---------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pageNum`  | `integer` | No       | `1`     | **Mutually Exclusive Group: Pagination Parameters** . 1-based page number; ignored when `offset` is provided. max: 9007199254740991              |
| `pageSize` | `integer` | No       | `20`    | **Mutually Exclusive Group: Pagination Parameters** . Items per page. Defaults to 20, capped at 500 (larger values are clamped to 500). max: 500 |

## Request Examples

Replace `YOUR_API_KEY` and placeholder IDs before running. Self-hosted users should replace the base URL with `<instance>/api` .

### cURL Example

```bash
curl --fail-with-body -X POST "https://cloud.fastgpt.io/api/core/dataset/data/v2/list" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "offset": 0,
  "collectionId": "68ad85a7463006c963799a06"
}'
```

### Minimal Valid JSON Body

```json
{
  "offset": 0,
  "collectionId": "68ad85a7463006c963799a06"
}
```

## Response Schema & Examples

Successful `/api/*` calls return the standard FastGPT envelope `{ "code": 200, "statusText": "", "message": "", "data": ... }` , where `data` matches the `200` schema below (when a payload schema is declared; otherwise refer to the status description for runtime `data` semantics).

### HTTP 200

Successfully returned paginated data items

**Content-Type** : `application/json`

| Field                    | Type            | Required | Default | Constraints & Description                                                                                                                                                                                                                                     |
| ------------------------ | --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `total`                  | `number`        | Yes      | `0`     | -                                                                                                                                                                                                                                                             |
| `list`                   | `object[]`      | Yes      | `[]`    | -                                                                                                                                                                                                                                                             |
| `list[]._id`             | `string`        | Yes      | -       | Data item ID. pattern: `^[0-9a-fA-F]{24}$`                                                                                                                                                                                                                    |
| `list[].datasetId`       | `string`        | Yes      | -       | Dataset ID. pattern: `^[0-9a-fA-F]{24}$`                                                                                                                                                                                                                      |
| `list[].collectionId`    | `string`        | Yes      | -       | Collection ID. pattern: `^[0-9a-fA-F]{24}$`                                                                                                                                                                                                                   |
| `list[].q`               | `string`        | No       | -       | Primary chunk content / question                                                                                                                                                                                                                              |
| `list[].a`               | `string`        | No       | -       | Supplementary answer / text                                                                                                                                                                                                                                   |
| `list[].imageId`         | `string`        | No       | -       | Image ID                                                                                                                                                                                                                                                      |
| `list[].imageSize`       | `number`        | No       | -       | Image size in bytes                                                                                                                                                                                                                                           |
| `list[].imagePreviewUrl` | `string`        | No       | -       | Image preview URL                                                                                                                                                                                                                                             |
| `list[].chunkIndex`      | `number`        | No       | -       | Chunk index                                                                                                                                                                                                                                                   |
| `list[].indexStatus`     | `string` (enum) | No       | -       | Index status (absent on legacy already-indexed records). Allowed values: `indexing` , `indexed` , `error` , `rebuildIndexPending` , `rebuildIndexRunning` , `rebuildIndexFailed` , `rebuildSynonymPending` , `rebuildSynonymRunning` , `rebuildSynonymFailed` |
| `list[].indexErrorMsg`   | `string`        | No       | -       | Indexing error details                                                                                                                                                                                                                                        |
| `list[].updated`         | `boolean`       | No       | -       | Whether the chunk has been updated since citation                                                                                                                                                                                                             |
