# List Datasets (V2)

> List accessible datasets and folders with pagination, ID lookup, keyword filtering, and optional collection file counts.

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

## Endpoint Overview

* **Method** : `POST`
* **Path** : `/api/core/dataset/listV2`
* **Module** : Datasets / Datasets
* **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/%E7%9F%A5%E8%AF%86%E5%BA%93%E7%AE%A1%E7%90%86/POST/core/dataset/listV2) (self-hosted instances: replace the origin with `<instance>/apidoc/systemopenapi#tag/%E7%9F%A5%E8%AF%86%E5%BA%93%E7%AE%A1%E7%90%86/POST/core/dataset/listV2` )

## Description & Notes

Queries accessible datasets with pagination or exact `datasetIds` lookup. When `datasetIds` is passed, `parentId` and pagination parameters are ignored while shared filters remain active.

## Request Parameters

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

#### Shared Parameters Across Branches

| Field           | Type              | Required | Default            | Constraints & Description                                                                                                                                                                                                                                                                                 |
| --------------- | ----------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`          | `string \| array` | No       | -                  | Dataset type filter                                                                                                                                                                                                                                                                                       |
| `searchKey`     | `string`          | No       | -                  | Search keyword matching dataset name and introduction                                                                                                                                                                                                                                                     |
| `sort`          | `string` (enum)   | No       | `"updateTimeDesc"` | Sort order; defaults to most recently updated descending. Allowed values: `updateTimeDesc` (Sort by update time descending (most recently modified first, default)), `createTimeDesc` (Sort by creation time descending (newest first)), `createTimeAsc` (Sort by creation time ascending (oldest first)) |
| `tmbIds`        | `string[]`        | No       | -                  | Filter by creator member IDs; an empty array returns an empty list                                                                                                                                                                                                                                        |
| `withAppCount`  | `boolean`         | No       | -                  | Whether to count referencing published apps (default `false` ; visible to non-folder owners only)                                                                                                                                                                                                         |
| `withFileCount` | `boolean`         | No       | -                  | Whether to compute total non-folder collection count across all depths (default `false` )                                                                                                                                                                                                                 |

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

* **Lookup by IDs**

| Field        | Type       | Required | Default | Constraints & Description                                                                                                                                                           |
| ------------ | ---------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `datasetIds` | `string[]` | Yes      | -       | Exact lookup by up to 500 dataset or folder IDs; takes precedence over pagination and strips `parentId` /pagination fields while keeping shared filters. minItems: 1; maxItems: 500 |

* **Paginated Lookup**

| Field      | Type             | Required | Default | Constraints & Description                                                                                                                |
| ---------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `parentId` | `string \| null` | No       | -       | Parent folder ID ( `null` or empty for root); omit to search across all readable datasets, or set to restrict search to a folder subtree |

**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/listV2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "datasetIds": [
    "68ad85a7463006c963799a05"
  ]
}'
```

### Minimal Valid JSON Body

```json
{
  "datasetIds": ["68ad85a7463006c963799a05"]
}
```

## 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 dataset list

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

| Field                                      | Type             | Required | Default            | Constraints & Description                                                                                                                                                                   |
| ------------------------------------------ | ---------------- | -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `total`                                    | `number`         | Yes      | `0`                | -                                                                                                                                                                                           |
| `list`                                     | `object[]`       | Yes      | `[]`               | -                                                                                                                                                                                           |
| `list[]._id`                               | `string`         | Yes      | -                  | Dataset ID. pattern: `^[0-9a-fA-F]{24}$`                                                                                                                                                    |
| `list[].tmbId`                             | `string`         | Yes      | -                  | Team member ID. pattern: `^[0-9a-fA-F]{24}$`                                                                                                                                                |
| `list[].avatar`                            | `string`         | Yes      | `"/icon/logo.svg"` | Avatar                                                                                                                                                                                      |
| `list[].createTime`                        | `string`         | Yes      | -                  | Creation time                                                                                                                                                                               |
| `list[].updateTime`                        | `string`         | Yes      | -                  | Update time                                                                                                                                                                                 |
| `list[].name`                              | `string`         | Yes      | -                  | Name                                                                                                                                                                                        |
| `list[].intro`                             | `string`         | Yes      | -                  | Introduction                                                                                                                                                                                |
| `list[].type`                              | `string` (enum)  | Yes      | -                  | Dataset type. Allowed values: `folder` , `dataset` , `websiteDataset` , `externalFile` , `apiDataset` , `feishu` , `yuque` , `dingtalk`                                                     |
| `list[].permission`                        | `object`         | Yes      | -                  | Serialized permission object JSON structure                                                                                                                                                 |
| `list[].permission.role`                   | `integer`        | Yes      | -                  | Permission role bitmask value. min: -9007199254740991; max: 9007199254740991                                                                                                                |
| `list[].permission.isOwner`                | `boolean`        | Yes      | -                  | Whether the caller has owner permission                                                                                                                                                     |
| `list[].permission.hasManagePer`           | `boolean`        | Yes      | -                  | Whether the caller has manage permission                                                                                                                                                    |
| `list[].permission.hasWritePer`            | `boolean`        | Yes      | -                  | Whether the caller has write permission                                                                                                                                                     |
| `list[].permission.hasReadPer`             | `boolean`        | Yes      | -                  | Whether the caller has read permission                                                                                                                                                      |
| `list[].permission.hasManageRole`          | `boolean`        | Yes      | -                  | Whether manage role bit is set                                                                                                                                                              |
| `list[].permission.hasWriteRole`           | `boolean`        | Yes      | -                  | Whether write role bit is set                                                                                                                                                               |
| `list[].permission.hasReadRole`            | `boolean`        | Yes      | -                  | Whether read role bit is set                                                                                                                                                                |
| `list[].appCount`                          | `integer`        | No       | -                  | Count of published apps referencing this dataset (returned only to non-folder owners when enabled). min: 0; max: 9007199254740991                                                           |
| `list[].fileCount`                         | `integer`        | No       | -                  | Total non-folder collection count across all depths (unfiltered by file permissions; returned only when `withFileCount` is requested on non-folder datasets). min: 0; max: 9007199254740991 |
| `list[].vectorModel`                       | `object`         | No       | -                  | Embedding model info (empty for folders or deleted models; inactive models still return display metadata)                                                                                   |
| `list[].vectorModel.pricing`               | `object`         | No       | -                  | Credit price per fixed billing unit; omitted if free                                                                                                                                        |
| `list[].vectorModel.pricing.unitPrice`     | `number`         | No       | -                  | Composite credit price per million units (tokens/TTS) or per 60 seconds (STT). min: 0                                                                                                       |
| `list[].vectorModel.provider`              | `string`         | Yes      | -                  | minLength: 1                                                                                                                                                                                |
| `list[].vectorModel.model`                 | `string`         | Yes      | -                  | minLength: 1                                                                                                                                                                                |
| `list[].vectorModel.name`                  | `string`         | Yes      | -                  | minLength: 1                                                                                                                                                                                |
| `list[].vectorModel.scope`                 | `string` (enum)  | Yes      | `"system"`         | Allowed values: `system` , `team`                                                                                                                                                           |
| `list[].vectorModel.sortOrder`             | `integer`        | No       | -                  | Display rank within the same scope (smaller numbers appear first). min: 0; max: 9007199254740991                                                                                            |
| `list[].vectorModel.tmbId`                 | `string \| null` | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.teamId`                | `string \| null` | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.isActive`              | `boolean`        | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.isUpcomingDeprecation` | `boolean`        | No       | -                  | Whether the model is scheduled for deprecation                                                                                                                                              |
| `list[].vectorModel.requestUrl`            | `string`         | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.requestAuth`           | `string`         | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.testMode`              | `boolean`        | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.type`                  | `"embedding"`    | Yes      | -                  | Fixed: `"embedding"`                                                                                                                                                                        |
| `list[].vectorModel.config`                | `object`         | Yes      | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.config.defaultToken`   | `number`         | Yes      | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.config.maxToken`       | `number`         | Yes      | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.config.weight`         | `number`         | Yes      | `0`                | -                                                                                                                                                                                           |
| `list[].vectorModel.config.hidden`         | `boolean`        | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.config.vision`         | `boolean`        | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.config.normalization`  | `boolean`        | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.config.batchSize`      | `number`         | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.config.defaultConfig`  | `object`         | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.config.dbConfig`       | `object`         | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.config.queryConfig`    | `object`         | No       | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.modelId`               | `string`         | Yes      | -                  | -                                                                                                                                                                                           |
| `list[].vectorModel.avatar`                | `string`         | No       | -                  | -                                                                                                                                                                                           |
| `list[].inheritPermission`                 | `boolean`        | Yes      | -                  | Whether permissions are inherited from parent                                                                                                                                               |
| `list[].private`                           | `boolean`        | No       | -                  | Whether access is private to the owner                                                                                                                                                      |
| `list[].folderAccessMode`                  | `string` (enum)  | No       | -                  | Folder access mode; `navigate` allows traversing readable descendants without granting direct read permission. Allowed values: `read` , `navigate`                                          |
| `list[].sourceMember`                      | `object`         | No       | -                  | Source member                                                                                                                                                                               |
| `list[].sourceMember.name`                 | `string`         | Yes      | -                  | Member name                                                                                                                                                                                 |
| `list[].sourceMember.avatar`               | `string \| null` | No       | -                  | Member avatar                                                                                                                                                                               |
| `list[].sourceMember.status`               | `string` (enum)  | Yes      | -                  | Member status. Allowed values: `active` , `leave` , `forbidden`                                                                                                                             |
