# Search Datasets API

> Search across one or more readable datasets with semantic/hybrid recall, reranking, tag filters, and topk/maxTokens limits.

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

## 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](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%E6%90%9C%E7%B4%A2/POST/core/dataset/search) (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

```bash
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

```json
{
  "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                                                                                                                                                                                                                             |
