---
title: "Retrieve Chunks from a Knowledge Base / Test Retrieval"
method: POST
path: "/datasets/{dataset_id}/retrieve"
tags: ["Knowledge Bases"]
---

# Retrieve Chunks from a Knowledge Base / Test Retrieval

`POST /datasets/{dataset_id}/retrieve`

Searches a knowledge base and returns the chunks most relevant to the query, for both production retrieval and test retrieval.

## Path parameters

- `dataset_id` string, uuid, required

## Request body

- object
  - `query` string, required — Search query text.
  - `retrieval_model` RetrievalModel
    - `search_method` 'keyword_search' | 'semantic_search' | 'full_text_search' | 'hybrid_search', required — Search method used for retrieval.
    - `reranking_enable` boolean, required — Whether reranking is enabled.
    - `reranking_model` object — Reranking model configuration.
      - `reranking_provider_name` string — Reranking model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/cohere/cohere`). A bare name like `cohere` expands to `langgenius/<name>/<name>` and works only for langgenius-published plugins. Get valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=rerank`.
      - `reranking_model_name` string — Name of the reranking model.
    - `reranking_mode` 'reranking_model' | 'weighted_score', nullable — Reranking mode. Required when `reranking_enable` is `true`.
    - `top_k` integer, required — Maximum number of results to return.
    - `score_threshold_enabled` boolean, required — Whether score threshold filtering is enabled.
    - `score_threshold` number, nullable — Minimum similarity score for results. Only effective when `score_threshold_enabled` is `true`.
    - `weights` object, nullable — Weight configuration for hybrid search.
      - `weight_type` 'semantic_first' | 'keyword_first' | 'customized' — Strategy for balancing semantic and keyword search weights.
      - `vector_setting` object — Semantic search weight settings.
        - `vector_weight` number — Weight assigned to semantic (vector) search results.
        - `embedding_provider_name` string — Provider of the embedding model used for vector search.
        - `embedding_model_name` string — Name of the embedding model used for vector search.
      - `keyword_setting` object — Keyword search weight settings.
        - `keyword_weight` number — Weight assigned to keyword search results.
    - `metadata_filtering_conditions` object, nullable — Restrict retrieval to chunks whose document metadata matches the given conditions. Conditions are evaluated server-side against document metadata fields.
      - `logical_operator` 'and' | 'or', nullable — How to combine multiple conditions.
      - `conditions` object[], nullable — List of metadata conditions to evaluate.
        - `name` string, required — Metadata field name to compare against.
        - `comparison_operator` 'contains' | 'not contains' | 'start with' | 'end with' | 'is' | 'is not' | 'empty' | 'not empty' | 'in' | 'not in' | '=' | '≠' | '>' | '<' | '≥' | '≤' | 'before' | 'after', required — Comparison to apply, by metadata type: - String or array metadata: `contains`, `not contains`, `start with`, `end with`, `is`, `is not`, `empty`, `not empty`, `in`, `not in` - Numeric metadata: `=`, `≠`, `>`, `<`, `≥`, `≤` - Time metadata: `before`, `after`
        - `value` union — Value to compare against. Type depends on `comparison_operator`: string for most string operators, array of strings for `in` and `not in`, number for numeric operators, and omitted for `empty` and `not empty`.
          - string
          - string[]
          - number
  - `attachment_ids` string[], nullable — List of attachment IDs to include in the retrieval context.
  - `external_retrieval_model` object — Retrieval settings for external knowledge bases.
    - `top_k` integer — Maximum number of results to return.
    - `score_threshold` number — Minimum similarity score threshold for filtering results.
    - `score_threshold_enabled` boolean — Whether score threshold filtering is enabled.

## Response `200`

Retrieval results.

- object
  - `query` object — The original query object.
    - `content` string — The query text.
  - `records` object[] — List of matched retrieval records.
    - `segment` object — Matched chunk from the knowledge base.
      - `id` string — Unique identifier of the chunk.
      - `position` integer — Position of the chunk within the document.
      - `document_id` string — ID of the document this chunk belongs to.
      - `content` string — Text content of the chunk.
      - `sign_content` string — Signed content hash for integrity verification.
      - `answer` string — Answer content, used in Q&A mode documents.
      - `word_count` integer — Word count of the chunk content.
      - `tokens` integer — Token count of the chunk content.
      - `keywords` string[] — Keywords associated with this chunk for keyword-based retrieval.
      - `index_node_id` string — ID of the index node in the vector store.
      - `index_node_hash` string — Hash of the indexed content, used to detect changes.
      - `hit_count` integer — Number of times this chunk has been matched in retrieval queries.
      - `enabled` boolean — Whether the chunk is enabled for retrieval.
      - `disabled_at` number, nullable — Timestamp when the chunk was disabled. `null` if enabled.
      - `disabled_by` string, nullable — ID of the user who disabled the chunk. `null` if enabled.
      - `status` string — Indexing status of the chunk.
      - `created_by` string — ID of the user who created the chunk.
      - `created_at` number — Creation timestamp (Unix epoch in seconds).
      - `indexing_at` number, nullable — Timestamp when indexing started. `null` if not yet started.
      - `completed_at` number, nullable — Timestamp when indexing completed. `null` if not yet completed.
      - `error` string, nullable — Error message if indexing failed. `null` when no error.
      - `stopped_at` number, nullable — Timestamp when indexing was stopped. `null` if not stopped.
      - `document` object — Parent document information for the matched chunk.
        - `id` string — Unique identifier of the document.
        - `data_source_type` string — How the document was created.
        - `name` string — Document name.
        - `doc_type` string, nullable — Document type classification. `null` if not set.
        - `doc_metadata` object, nullable — Metadata values for the document. `null` if no metadata is configured.
    - `child_chunks` object[] — Matched child chunks within the chunk, if using hierarchical indexing.
      - `id` string — Unique identifier of the child chunk.
      - `content` string — Text content of the child chunk.
      - `position` integer — Position of the child chunk within the parent chunk.
      - `score` number — Similarity score of the child chunk.
    - `score` number — Similarity score.
    - `tsne_position` object, nullable — t-SNE visualization position.
    - `files` object[] — Files attached to this chunk.
      - `id` string — Attachment file identifier.
      - `name` string — Original file name.
      - `size` integer — File size in bytes.
      - `extension` string — File extension.
      - `mime_type` string — MIME type of the file.
      - `source_url` string — URL to access the attachment.
    - `summary` string, nullable — Summary content if retrieved via summary index.

## Other responses

- `400` — - `dataset_not_initialized` : The knowledge base is still initializing or indexing. - `provider_not_initialize` : The model provider has no valid credentials configured. - `provider_quota_exceeded` : The Dify-hosted model provider quota is exhausted. - `model_currently_not_support` : The selected model is not currently supported. - `completion_request_error` : The model request failed. - `invalid_param` : A request parameter is invalid.
- `403` — - `forbidden` : API access is not enabled for this knowledge base. - `forbidden` : Your subscription's knowledge base request rate limit has been reached.
- `404` — `not_found` : No knowledge base matches `dataset_id`.
- `500` — `internal_server_error` : An internal error occurred during retrieval.

---

[API](https://skmtc.net/langgenius/apis/dify-service-api.md) · [All operations](https://skmtc.net/langgenius/apis/dify-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/langgenius/dify-service-api/revisions/e49b3db72bad/schema)