FastGPTFastGPT

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

FieldTypeRequiredDefaultConstraints & Description
typestring | arrayNo-Dataset type filter
searchKeystringNo-Search keyword matching dataset name and introduction
sortstring (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))
tmbIdsstring[]No-Filter by creator member IDs; an empty array returns an empty list
withAppCountbooleanNo-Whether to count referencing published apps (default false ; visible to non-folder owners only)
withFileCountbooleanNo-Whether to compute total non-folder collection count across all depths (default false )

Mutually Exclusive Branches ( anyOf )

  • Lookup by IDs
FieldTypeRequiredDefaultConstraints & Description
datasetIdsstring[]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
FieldTypeRequiredDefaultConstraints & Description
parentIdstring | nullNo-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.

FieldTypeRequiredDefaultConstraints & Description
offsetintegerYes-Mutually Exclusive Group: Pagination Parameters . 0-based offset. min: 0; max: 9007199254740991
pageSizeintegerNo20Mutually 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.

FieldTypeRequiredDefaultConstraints & Description
pageNumintegerNo1Mutually Exclusive Group: Pagination Parameters . 1-based page number; ignored when offset is provided. max: 9007199254740991
pageSizeintegerNo20Mutually 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

FieldTypeRequiredDefaultConstraints & Description
totalnumberYes0-
listobject[]Yes[]-
list[]._idstringYes-Dataset ID. pattern: ^[0-9a-fA-F]{24}$
list[].tmbIdstringYes-Team member ID. pattern: ^[0-9a-fA-F]{24}$
list[].avatarstringYes"/icon/logo.svg"Avatar
list[].createTimestringYes-Creation time
list[].updateTimestringYes-Update time
list[].namestringYes-Name
list[].introstringYes-Introduction
list[].typestring (enum)Yes-Dataset type. Allowed values: folder , dataset , websiteDataset , externalFile , apiDataset , feishu , yuque , dingtalk
list[].permissionobjectYes-Serialized permission object JSON structure
list[].permission.roleintegerYes-Permission role bitmask value. min: -9007199254740991; max: 9007199254740991
list[].permission.isOwnerbooleanYes-Whether the caller has owner permission
list[].permission.hasManagePerbooleanYes-Whether the caller has manage permission
list[].permission.hasWritePerbooleanYes-Whether the caller has write permission
list[].permission.hasReadPerbooleanYes-Whether the caller has read permission
list[].permission.hasManageRolebooleanYes-Whether manage role bit is set
list[].permission.hasWriteRolebooleanYes-Whether write role bit is set
list[].permission.hasReadRolebooleanYes-Whether read role bit is set
list[].appCountintegerNo-Count of published apps referencing this dataset (returned only to non-folder owners when enabled). min: 0; max: 9007199254740991
list[].fileCountintegerNo-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[].vectorModelobjectNo-Embedding model info (empty for folders or deleted models; inactive models still return display metadata)
list[].vectorModel.pricingobjectNo-Credit price per fixed billing unit; omitted if free
list[].vectorModel.pricing.unitPricenumberNo-Composite credit price per million units (tokens/TTS) or per 60 seconds (STT). min: 0
list[].vectorModel.providerstringYes-minLength: 1
list[].vectorModel.modelstringYes-minLength: 1
list[].vectorModel.namestringYes-minLength: 1
list[].vectorModel.scopestring (enum)Yes"system"Allowed values: system , team
list[].vectorModel.sortOrderintegerNo-Display rank within the same scope (smaller numbers appear first). min: 0; max: 9007199254740991
list[].vectorModel.tmbIdstring | nullNo--
list[].vectorModel.teamIdstring | nullNo--
list[].vectorModel.isActivebooleanNo--
list[].vectorModel.isUpcomingDeprecationbooleanNo-Whether the model is scheduled for deprecation
list[].vectorModel.requestUrlstringNo--
list[].vectorModel.requestAuthstringNo--
list[].vectorModel.testModebooleanNo--
list[].vectorModel.type"embedding"Yes-Fixed: "embedding"
list[].vectorModel.configobjectYes--
list[].vectorModel.config.defaultTokennumberYes--
list[].vectorModel.config.maxTokennumberYes--
list[].vectorModel.config.weightnumberYes0-
list[].vectorModel.config.hiddenbooleanNo--
list[].vectorModel.config.visionbooleanNo--
list[].vectorModel.config.normalizationbooleanNo--
list[].vectorModel.config.batchSizenumberNo--
list[].vectorModel.config.defaultConfigobjectNo--
list[].vectorModel.config.dbConfigobjectNo--
list[].vectorModel.config.queryConfigobjectNo--
list[].vectorModel.modelIdstringYes--
list[].vectorModel.avatarstringNo--
list[].inheritPermissionbooleanYes-Whether permissions are inherited from parent
list[].privatebooleanNo-Whether access is private to the owner
list[].folderAccessModestring (enum)No-Folder access mode; navigate allows traversing readable descendants without granting direct read permission. Allowed values: read , navigate
list[].sourceMemberobjectNo-Source member
list[].sourceMember.namestringYes-Member name
list[].sourceMember.avatarstring | nullNo-Member avatar
list[].sourceMember.statusstring (enum)Yes-Member status. Allowed values: active , leave , forbidden
Edit on GitHub

Last updated

On this page

Put your business knowledge to work with AI

Import company documents and build accurate, reliable, traceable AI answers.