FastGPTFastGPT

List Dataset Collections (V2)

Query paginated collections and folders inside a dataset with keyword search, structured tag filters, and permission checks.

Endpoint Overview

  • Method : POST
  • Path : /api/core/dataset/collection/listV2
  • Module : Datasets / Collections
  • 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/%E9%9B%86%E5%90%88%E7%AE%A1%E7%90%86/POST/core/dataset/collection/listV2 )

Description & Notes

List collections in a dataset with pagination, search, and tag filters (requires dataset read permission and parent folder read permission when parentId is specified). When collection-level permissions are enabled, results are filtered per collection with effective permissions returned.

Request Parameters

Request Body ( application/json )

Shared Parameters Across Branches

FieldTypeRequiredDefaultConstraints & Description
datasetIdstringYes-Dataset ID
parentIdstring | nullNonullParent folder ID
searchTextstringNo""Search query text. maxLength: 100
selectFolderbooleanNofalseReturn folders only
tagFiltersobject[]No-Filter by tag values (OR across values of the same tag, AND across distinct tags)
tagFilters[].tagIdstringYes-Tag ID. pattern: ^[0-9a-fA-F]{24}$
tagFilters[].valuesstring | number[]Yes-Selected tag values (strings for text/select, numbers for numeric, UTC millisecond timestamps for dates; OR across values of the same tag). minItems: 1
sortBystring (enum)No"updateTime"Sort field supporting name, creation time, and update time. Allowed values: name , createTime , updateTime
sortOrderstring (enum)No"desc"Sort direction. Allowed values: asc , desc
simplebooleanNofalseSimple mode (skips total item counts)

Mutually Exclusive Branches ( anyOf )

  • 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/collection/listV2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "offset": 0,
  "datasetId": "string"
}'

Minimal Valid JSON Body

{
  "offset": 0,
  "datasetId": "string"
}

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 collection list and total count

Returns the standard FastGPT success envelope ( { "code": 200, "statusText": "", "message": "", "data": ... } ). The exact data payload schema is not declared in this OpenAPI contract; refer to the status description above or inspect runtime responses.

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.