List Datasets (V2)
List accessible datasets and folders with pagination, ID lookup, keyword filtering, and optional collection file counts.
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 ) - Interactive Try-It-Out : Open in Scalar API Explorer (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
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
{
"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 |
Last updated