---
title: "获取知识文档解析的 Span 树（含历史尝试）"
method: GET
path: "/knowledge/{id}/spans"
tags: ["知识管理"]
---

# 获取知识文档解析的 Span 树（含历史尝试）

`GET /knowledge/{id}/spans`

## Request

- Base URL: `/api/v1` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/v1/knowledge/{id}/spans`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `X-API-Key`

返回该知识在解析流水线的 trace tree（root → stage → subspan）：每段状态、耗时、input/output、错误码、langfuse_trace_id。支持 ?attempt=N 查看历史尝试；不传则返回最新尝试。前端用于渲染时间线 + 多模态/embedding 子节点 + 一键跳转 Langfuse。

## Path parameters

- `id` string, required

## Query parameters

- `attempt` integer

## Response `200`

OK

- object
  - `data` InternalHandlerKnowledgeSpansData
    - `attempt` integer: Attempt is the attempt the trace describes; equals CurrentAttempt.
    - `current_attempt` integer
    - `current_stage` string: CurrentStage is the stage running now, or the last one that ran.
    - `knowledge_id` string
    - `last_activity_at` string: LastActivityAt is set while the parse is in flight.
    - `last_error` InternalHandlerKnowledgeSpanError
      - `code` string
      - `error_code` string
      - `error_message` string
      - `finished_at` string
      - `message` string
      - `name` string
      - `stage` string
    - `latest_attempt` integer
    - `parse_status` string
    - `stall_state` string: StallState is types.StallStateQueued or types.StallStateStalled when an in-flight parse has gone quiet.
    - `trace` GithubComTencentWeKnoraInternalTypesSpanTreeNode
      - `attempt` integer
      - `children` GithubComTencentWeKnoraInternalTypesSpanTreeNode[]
      - `created_at` string
      - `duration_ms` integer
      - `error_code` string
      - `error_message` string
      - `finished_at` string
      - `input` GithubComTencentWeKnoraInternalTypesJSONMap
      - `kind` string
      - `knowledge_id` string
      - `metadata` GithubComTencentWeKnoraInternalTypesJSONMap
      - `name` string
      - `output` GithubComTencentWeKnoraInternalTypesJSONMap
      - `parent_span_id` string
      - `span_id` string
      - `started_at` string
      - `status` string
      - `updated_at` string
  - `success` boolean

## Other responses

- `403`: 无权访问所属知识库
- `404`: 知识不存在

## Changes

- **2026-10-14** `7909fe890afd`: 2 info
  - added the non-success response with the status `403`
  - added the non-success response with the status `404`
- **2026-10-14** `a1c41ab134cc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tencentblueking/apis/weknora-api/changes/knowledge/:id/spans/get.md)

---

[API](https://skmtc.dev/tencentblueking/apis/weknora-api.md) - [All operations](https://skmtc.dev/tencentblueking/apis/weknora-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tencentblueking/apis/weknora-api/revisions/685d1f9fce30?raw)