Run Query

Runs the query that Create Query Token issued a token for and streams the answer as Server-Sent Events. The credential is the query token, not the knowledge base API key. The token is checked when the request is accepted.

For the two-call flow and how to read the stream, see Query the Knowledge Base.

For which errors to retry and what the error details mean, see Handle Errors.

A successful query saves its query record before sending answer.done. Repeating the call runs the query again.

1 min read

post/knowledge-fs/query-stream

Request example

curl --request POST \
  --url https://api.dify.ai/v1/knowledge-fs/query-stream \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Trace-ID: <string>' \
  --header 'Content-Type: application/json' \
  --data '{
  "activeDocumentIds": [],
  "activeEntityIds": [],
  "knowledgeSpaceId": "8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f",
  "mode": "fast",
  "query": "What changed in the refund policy this quarter?"
}'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/query-stream"
headers = {
    "Authorization": "Bearer <token>",
    "X-Trace-ID": "<string>",
    "Content-Type": "application/json",
}
payload = {
    "activeDocumentIds": [],
    "activeEntityIds": [],
    "knowledgeSpaceId": "8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f",
    "mode": "fast",
    "query": "What changed in the refund policy this quarter?"
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/knowledge-fs/query-stream', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'X-Trace-ID': '<string>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "activeDocumentIds": [],
    "activeEntityIds": [],
    "knowledgeSpaceId": "8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f",
    "mode": "fast",
    "query": "What changed in the refund policy this quarter?"
  })
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/knowledge-fs/query-stream',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "activeDocumentIds": [],
  "activeEntityIds": [],
  "knowledgeSpaceId": "8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f",
  "mode": "fast",
  "query": "What changed in the refund policy this quarter?"
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'X-Trace-ID: <string>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/knowledge-fs/query-stream"
	payload := strings.NewReader("{\n  \"activeDocumentIds\": [],\n  \"activeEntityIds\": [],\n  \"knowledgeSpaceId\": \"8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f\",\n  \"mode\": \"fast\",\n  \"query\": \"What changed in the refund policy this quarter?\"\n}")

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Trace-ID", "<string>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/knowledge-fs/query-stream"))
    .header("Authorization", "Bearer <token>")
    .header("X-Trace-ID", "<string>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"activeDocumentIds\": [],\n  \"activeEntityIds\": [],\n  \"knowledgeSpaceId\": \"8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f\",\n  \"mode\": \"fast\",\n  \"query\": \"What changed in the refund policy this quarter?\"\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/knowledge-fs/query-stream')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['X-Trace-ID'] = '<string>'
request['Content-Type'] = 'application/json'
request.body = '{
  "activeDocumentIds": [],
  "activeEntityIds": [],
  "knowledgeSpaceId": "8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f",
  "mode": "fast",
  "query": "What changed in the refund policy this quarter?"
}'

response = http.request(request)
puts response.read_body

Response

<string>

{
  "code": "KNOWLEDGE_FS_INVALID_REQUEST",
  "error": "The Agent Knowledge Base request is invalid.",
  "failure": {
    "category": "validation",
    "code": "KNOWLEDGE_FS_INVALID_REQUEST",
    "message": "The Agent Knowledge Base request is invalid.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "RETRIEVAL_PROFILE_SCORE_THRESHOLD_REQUIRES_RERANK",
  "error": "The Agent Knowledge Base request is invalid.",
  "failure": {
    "category": "validation",
    "code": "KNOWLEDGE_FS_INVALID_REQUEST",
    "message": "The Agent Knowledge Base request is invalid.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  },
  "mode": "fast"
}

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400
}

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400,
  "violations": [
    {
      "field": [
        "knowledgeSpaceId"
      ],
      "type": "missing"
    }
  ]
}

{
  "code": "KNOWLEDGE_FS_ACCESS_DENIED",
  "error": "You do not have permission to perform this Agent Knowledge Base operation.",
  "failure": {
    "action": "contact_admin",
    "category": "authorization",
    "code": "KNOWLEDGE_FS_ACCESS_DENIED",
    "message": "You do not have permission to perform this Agent Knowledge Base operation.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "knowledge_fs_invalid_credential",
  "message": "Invalid Agent Knowledge Base service credential.",
  "status": 401
}

{
  "code": "KNOWLEDGE_FS_ACCESS_DENIED",
  "error": "You do not have permission to perform this Agent Knowledge Base operation.",
  "failure": {
    "action": "contact_admin",
    "category": "authorization",
    "code": "KNOWLEDGE_FS_ACCESS_DENIED",
    "message": "You do not have permission to perform this Agent Knowledge Base operation.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "KNOWLEDGE_FS_NOT_FOUND",
  "error": "The requested Agent Knowledge Base resource was not found.",
  "failure": {
    "category": "not_found",
    "code": "KNOWLEDGE_FS_NOT_FOUND",
    "message": "The requested Agent Knowledge Base resource was not found.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "QUERY_IMAGE_NOT_FOUND",
  "error": "The requested Agent Knowledge Base resource was not found.",
  "failure": {
    "category": "not_found",
    "code": "KNOWLEDGE_FS_NOT_FOUND",
    "message": "The requested Agent Knowledge Base resource was not found.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "not_found",
  "message": "The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.",
  "status": 404
}

{
  "code": "RETRIEVAL_DELETION_IN_PROGRESS",
  "error": "This Agent Knowledge Base is being deleted and cannot be searched.",
  "failure": {
    "category": "conflict",
    "code": "RETRIEVAL_DELETION_IN_PROGRESS",
    "message": "This Agent Knowledge Base is being deleted and cannot be searched.",
    "retryPolicy": "never",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "RETRIEVAL_EXECUTION_LEASE_LOST",
  "error": "The retrieval execution expired before it could finish. Run the query again.",
  "failure": {
    "action": "retry",
    "category": "conflict",
    "code": "RETRIEVAL_EXECUTION_LEASE_LOST",
    "message": "The retrieval execution expired before it could finish. Run the query again.",
    "retryPolicy": "manual",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "knowledge_fs_request_too_large",
  "message": "Agent Knowledge Base request is too large.",
  "status": 413
}

{
  "code": "KNOWLEDGE_FS_INTERNAL_ERROR",
  "error": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
  "failure": {
    "action": "contact_admin",
    "category": "internal",
    "code": "KNOWLEDGE_FS_INTERNAL_ERROR",
    "message": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
    "retryPolicy": "manual",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "knowledge_fs_upstream_unavailable",
  "message": "Agent Knowledge Base is unavailable.",
  "status": 502
}

{
  "code": "KNOWLEDGE_FS_UNAVAILABLE",
  "error": "Agent Knowledge Base is temporarily unavailable. Try again later.",
  "failure": {
    "action": "retry",
    "category": "dependency",
    "code": "KNOWLEDGE_FS_UNAVAILABLE",
    "message": "Agent Knowledge Base is temporarily unavailable. Try again later.",
    "retryPolicy": "manual",
    "traceId": "3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60"
  }
}

{
  "code": "knowledge_fs_operation_unavailable",
  "message": "Agent Knowledge Base operation is not available.",
  "status": 503
}

post/knowledge-fs/query-stream

Authorization

Authorizationstringheaderrequired#

The query token returned by Create Query Token, sent as Authorization: Bearer {token}. Use it before the returned expires_at time, at most 60 seconds after issue. It authorizes only Run Query on that knowledge base.

Send X-Trace-ID on the same request, with the trace_id that Create Query Token returned.

Headers

X-Trace-IDstringrequired#

The trace_id from the Create Query Token response, the same value as the token's trace_id claim. A value that does not match the token is rejected with 403. See Query the Knowledge Base.

Body

application/json

activeDocumentIdsstring[]#

Copied from the returned request object. These IDs do not filter or rank retrieved content.

Items: max 100

activeEntityIdsstring[]#

Copied from the returned request object. These IDs do not filter or rank retrieved content.

Items: max 100

knowledgeSpaceIdstringrequired#

Internal ID of the knowledge base, copied from the request object of Create Query Token. Must match the token. A mismatch is rejected with 403.

Length: min 1

modeenum<string>#

Retrieval depth, copied from the request object of Create Query Token. null is accepted and means the knowledge base's default depth.

Options:fastdeepresearchnull

querystringrequired#

The question. Use a nonblank query. Also limited to 16,384 UTF-8 bytes.

Length: max 16000Pattern: \S

sessionIdstring#

Session ID, copied from the request object of Create Query Token.

Responses

text/event-stream

The stream opened. Events follow as text/event-stream, whatever Accept the request sends. Before the stream opens, handle failures as HTTP errors. After it opens, handle an answer.error event as failure even though the HTTP status is 200.

Create Query Token List Query Records