Get Research Task

Returns the current state of a research task: stage, cost so far, limits, timestamps, and error details when it failed.

Poll until stage is completed, failed, or canceled. The answer is not on this object. For the plan, create, poll, and read flow, see Run a Research Task.

GET /knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}

Get Research Task

cURL

curl --request GET \
  --url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id} \
  --header 'Authorization: Bearer <token>'

200

budget_canceled

{
  "budget_usd": 0.01,
  "completed_at": 1788681618000,
  "cost": {
    "budgetExceeded": true,
    "budgetUsd": 0.01,
    "entries": [
      {
        "costUsd": 0.0011,
        "provider": "openai",
        "recordedAt": 1788681603000,
        "step": "research.plan",
        "usage": {
          "completionTokens": 58,
          "estimated": false,
          "promptTokens": 310,
          "researchModelCallId": "attempt:1:call-4",
          "reserved": false,
          "status": "succeeded",
          "totalTokens": 368
        }
      },
      {
        "costUsd": 0.0096,
        "provider": "openai",
        "recordedAt": 1788681618000,
        "step": "research.judge",
        "usage": {
          "completionTokens": 190,
          "estimated": false,
          "promptTokens": 2640,
          "researchModelCallId": "attempt:1:call-5",
          "reserved": false,
          "status": "succeeded",
          "totalTokens": 2830
        }
      }
    ],
    "totalUsd": 0.0107
  },
  "created_at": 1788681600000,
  "error": null,
  "failure": null,
  "id": "e4d1b7a2-3c5f-4d8e-9a0b-1c2d3e4f5a6b",
  "knowledge_space_id": "b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d",
  "limits": {
    "max_retrieval_steps": 8,
    "max_scanned_resources": 800,
    "max_tool_calls": 12,
    "timeout_ms": 120000
  },
  "metadata": {
    "client_request_id": "client-20260907-0001",
    "ticket": "SUP-1042"
  },
  "mode": "research",
  "query": "What changed in the 2025 refund policy, and which regions are affected?",
  "stage": "canceled",
  "top_k": 10,
  "updated_at": 1788681618000
}

Authorizations

Authorization · string · header · required

Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Path Parameters

knowledge_base_id · string<uuid> · required

Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's API Access dialog (…/knowledge-fs/spaces/<knowledge base ID>), and the segment after /datasets/new/ in the address bar.

research_task_id · string<uuid> · required

Research task ID. From Create Research Task.

Response

200

application/json

The research task.

budget_usd · number | null

Spend ceiling from the request in USD. null when none was set.

completed_at · number | null

When the task reached completed, failed, or canceled, in epoch milliseconds. null while the task is running.

cost · object

Spend recorded so far.

Show child attributes

created_at · number

Epoch milliseconds when the task was created.

error · string | null

Failure code, the same value as failure.code. Present only when stage is failed, and null otherwise, including for canceled tasks.

On a failed research task, failure.code is one of RESEARCH_TASK_CAPABILITY_REVOKED, RESEARCH_TASK_DISPATCH_DEAD, RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED, RESEARCH_TASK_FAILED, RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID, or RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID.

failure · object | null

Error details. Present only when stage is failed, and null otherwise. Members without a value are null here. traceId is the task ID.

When action is retry, create a new task with Create Research Task.

Show child attributes

id · string

Research task ID. Use it as research_task_id in the task operations.

knowledge_space_id · string

Internal ID of the knowledge base. Not the knowledge base ID in the path.

limits · object | null

Limits from the request, with snake_case keys. null when the request carried no limits. A member that was not sent is null. Convert the keys back to camelCase before sending them to Create Research Task again.

Show child attributes

metadata · object

The metadata object sent at creation, without keys that start with __knowledgeFs.

mode · string | null

Retrieval depth of the task: fast, deep, or research.

query · string

The research question as stored.

query_images · object[]

Images used in the original query. Omitted for text-only queries.

Show child attributes

stage · string

Where the task is in its lifecycle. Tasks move forward one stage at a time:

• queued: accepted, waiting for a worker.
• planning: resolving the retrieval plan.
• retrieving: searching the knowledge base. A retrieval checkpoint may be written.
• analyzing: reading and weighing the retrieved chunks.
• generating: writing the answer. The final result is written during this stage.
• completed: finished. Read its results with List Research Task Results.
• failed: stopped with an error. See error and failure.
• canceled: stopped by Cancel Research Task or by the budget.
• paused: The task is paused. Check any failure details with the deployment operator, or cancel it.

completed, failed, and canceled are terminal.

top_k · integer | null

Maximum number of chunks kept after the search results are merged and reranked: the request's topK, or the knowledge base's TOP K when omitted.

updated_at · number

Epoch milliseconds of the last update to the task record, including internal checkpoints and retry scheduling.