Search Datasets API
Search across one or more readable datasets with semantic/hybrid recall, reranking, tag filters, and topk/maxTokens limits.
Endpoint Overview
- Method :
POST - Path :
/api/core/dataset/search - Module : Datasets / Dataset Search
- 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%E6%90%9C%E7%B4%A2/POST/core/dataset/search)
Description & Notes
Search across one or more readable datasets using an API Key or login session. Vector recall requires matching active embedding models across target datasets, and results respect collection-level permissions. Choose either result.topk (returns top 1–100 items without token truncation) or result.maxTokens (truncates on complete chunks with no fixed cap); defaults to topk=20 when omitted, and prioritizes topk if both are sent. Response meta reports effective execution parameters.
Request Parameters
Request Body ( application/json )
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
scope | object | Yes | - | Search scope |
scope.datasetIds | string[] | Yes | - | Target dataset IDs (max 100; deduplicated server-side with per-dataset read permission checks). minItems: 1; maxItems: 100 |
scope.filter | object | No | - | Collection and tag filters (requires server-side filter support) |
scope.filter.collectionIds | string[] | No | - | Restrict search to these collections or folders (intersected with other filters). minItems: 1; maxItems: 500 |
scope.filter.createTime | object | No | - | Collection creation time range |
scope.filter.createTime.gte | string | No | - | Inclusive lower bound of creation time. pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
scope.filter.createTime.lte | string | No | - | Inclusive upper bound of creation time. pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
scope.filter.tags | object | No | - | Tag filter conditions; and and or groups are intersected |
scope.filter.tags.and | object[] | No | - | Tag conditions where all entries must match (AND). minItems: 1; maxItems: 50 |
scope.filter.tags.or | object[] | No | - | Tag conditions where at least one entry must match (OR). minItems: 1; maxItems: 50 |
query | object | Yes | - | Search query input |
query.text | string | Yes | - | Branch: text . Query text (max 10,000 chars after trimming); at least one of text or queryImageUrls is required. minLength: 1; maxLength: 10000 |
query.imageKeys | string[] | No | [] | Branch: text . Temporary object keys for team-uploaded query images (max 10). maxItems: 10 |
query.imageKeys | string[] | Yes | - | Branch: imageKeys . Temporary object keys for team-uploaded query images (max 10). minItems: 1; maxItems: 10 |
query.text | string | No | "" | Branch: imageKeys . Query text (max 10,000 chars after trimming); at least one of text or queryImageUrls is required. maxLength: 10000 |
retrieval | object | No | {} | Recall configuration |
retrieval.mode | string (enum) | No | "embedding" | embedding , fullTextRecall , or mixedRecall . Allowed values: embedding , fullTextRecall , mixedRecall |
retrieval.embeddingWeight | number | No | 0.5 | Embedding fusion weight in mixed recall. min: 0; max: 1 |
rerank | object | No | {"enabled":false} | Rerank configuration; do not pass model or weight when disabled |
rerank.enabled | false | Yes | - | Branch: enabled=false . Disable Rerank. Fixed: false |
rerank.enabled | true | Yes | - | Branch: enabled=true . Enable Rerank. Fixed: true |
rerank.modelId | string | No | - | Branch: enabled=true . Rerank model ID; uses the default accessible model if omitted. minLength: 1 |
rerank.candidateNum | integer | No | - | Branch: enabled=true . Rerank candidate pool size ( 10–100 ; defaults to 100 ). min: 10; max: 100 |
rerank.weight | number | No | 0.5 | Branch: enabled=true . Fusion weight for rerank scores. min: 0; max: 1 |
queryExtension | object | No | {"enabled":false} | Query extension configuration |
queryExtension.enabled | false | Yes | - | Branch: enabled=false . Disable Query Extension. Fixed: false |
queryExtension.enabled | true | Yes | - | Branch: enabled=true . Enable Query Extension. Fixed: true |
queryExtension.modelId | string | No | - | Branch: enabled=true . Rerank model ID; uses the default accessible model if omitted. minLength: 1 |
queryExtension.background | string | No | "" | Branch: enabled=true . Background context helping the model interpret the query. maxLength: 100000 |
result | object | No | {} | Specify either topk or maxTokens ; defaults to topk=20 with no token budget |
result.similarity | number | No | 0 | Minimum similarity score threshold (applied when usingSimilarityFilter is enabled). min: 0; max: 1 |
result.maxTokens | integer | Yes | - | Branch: maxTokens . Total token budget across returned chunks (no fixed cap; preserves complete chunks, so the final chunk may exceed the budget). min: 1; max: 9007199254740991 |
result.topk | integer | No | 20 | Branch: anyOf #2 . Return top k ranked results ( 1–100 ; defaults to 20 when neither budget is set). min: 1; max: 100 |
usageScene | string (enum) | No | "search" | Billing label: search for Dataset Search or searchTest for Search Test (does not affect retrieval or permissions). Allowed values: search , searchTest |
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/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
--data-raw '{
"scope": {
"datasetIds": [
"507f1f77bcf86cd799439011"
]
},
"query": {
"text": "How do I create a dataset?"
}
}'Minimal Valid JSON Body
{
"scope": {
"datasetIds": ["507f1f77bcf86cd799439011"]
},
"query": {
"text": "How do I create a dataset?"
}
}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
Matched chunks and effective search metadata
Content-Type : application/json
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
list | object[] | Yes | - | Merged and ranked dataset chunks |
list[].q | string | Yes | - | Primary chunk content / question |
list[].a | string | No | - | Supplementary answer / text |
list[].imageId | string | No | - | Image ID |
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[].imagePreivewUrl | string | No | - | Image preview URL |
list[].updateTime | string | Yes | - | Update time |
list[].sourceName | string | Yes | - | Source name |
list[].sourceId | string | No | - | Source ID |
list[].chunkIndex | number | Yes | - | 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[].imageDescMap | object | No | - | Image description mapping |
list[].score | object[] | Yes | - | Retrieval score breakdown list |
list[].score[].type | string (enum) | Yes | - | Score type. Allowed values: embedding , fullText , reRank , rrf |
list[].score[].value | number | Yes | - | Score value |
list[].score[].index | number | Yes | - | Index |
list[].metadata | object | No | - | Custom metadata |
list[].retrievalRank | number | No | - | Retrieval rank |
list[].synonymMappings | object | No | - | Mapping from original terms appearing in chunks or user questions to canonical terms |
meta | object | Yes | - | - |
meta.durationMs | number | Yes | - | Search latency in milliseconds. min: 0 |
meta.usingSimilarityFilter | boolean | Yes | - | Whether similarity filtering was applied |
meta.usingReRank | boolean | Yes | - | Whether reranking was executed |
meta.queryExtensionModelId | string | No | - | Model ID used for query extension |
Last updated