List Dataset Data Items
Paginate through data chunks within a dataset collection with keyword search across question/answer fields and image URLs.
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 ) - Interactive Try-It-Out : Open in Scalar API Explorer (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
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
{
"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 |
Last updated