查询 Trace 列表

查询 Trace 列表。

基础信息

请求方式	`POST`
请求地址	`https://api.coze.cn/v1/loop/spans/search`
权限	`listLoopTrace` 确保调用该接口使用的访问令牌开通了 `listLoopTrace` 权限，详细信息参考鉴权方式。
QPS 限制	每个空间每秒最多调用 1 次。

请求参数

Header

参数	类型/取值	是否必选	示例	说明
Authorization	string	必选	`Bearer {your token}`	Bearer {your token}，注意有空格。
Content-Type	string	必选	`application/json`	请求体格式。
X-Tt-Logid	string	可选	-	链路 logid，建议显示透传，方便排查问题。
agw-js-conv	string	可选	`str`	填 `str`。

Body

参数	类型	是否必选	示例	说明
workspace_id	String	必选	`{实际空间id}`	扣子罗盘空间 ID。详细获取方式参考获取扣子罗盘空间 ID。
start_time	String	必选	`1754156936208`	开始时间（毫秒）。
end_time	String	必选	`1756221000000`	结束时间（毫秒）。
filters	Object	可选	-	查询条件组。详见 filters Object。
page_size	i32	可选	`1`	分页大小，最大 200，默认 100。
page_token	String	可选	-	下一页的游标，从返回结果获取。
order_bys	Array	可选	-	排序（只支持 `start_time` 的倒排）。详见 order_bys Object。
platform_type	String	必选	`coze_project`	支持：`cozeloop`、`coze_project`、`coze_workflow`、`coze_bot`、`veadk`。
span_list_type	String	可选	`all_span`	查询 span 类型，默认 `root_span`；当前支持：`all_span`、`root_span`。

filters Object

参数	类型	是否必选	示例	说明
query_and_or	String	可选	`and` / `or`	条件组之间的关系 `and` / `or`。
filter_fields	Array	必选	-	条件。
filter_fields.field_name	String	必选	`trace_id`	条件字段名。
filter_fields.field_type	String	必选	`string`	条件字段类型：`string`、`long`、`double`、`bool`。
filter_fields.values	Array of string	可选	`["29a2cfed1e409cb765e5b4f0632eb42c"]`	条件字段值。
filter_fields.query_type	String	可选	`eq`	查询算子：`match`、`eq`、`not_eq`、`lte`、`gte`、`lt`、`gt`、`exist`、`not_exist`、`in`、`not_in`。
filter_fields.query_and_or	String	可选	-	和子查询组的关系。
filter_fields.sub_filter	Array	可选	-	子查询组，同 `filter_fields`。

order_bys Object

参数	类型	是否必选	示例	说明
field	String	可选	`start_time`	排序字段。
is_asc	Bool	可选	`false`	是否升序。

返回参数

参数	类型	示例	说明
code	Int	`0`	错误码，非 0 表示失败。
msg	String	`""`	错误信息的描述。
data	Object	-	返回数据主体。
data.has_more	Bool	`false`	是否还有下一页。
data.next_page_token	String	`eyJTdGFydFRpbWUiOjE3NTYwOTUwMDAwMDAwMDAsIlNwYW5JRCI6IjEyMzQ1Njc4MTIzNDU2OTUifQ==`	下一页的 page token。
data.spans	Array of span	-	span 列表。

span 结构参考

type OutputSpan struct {
    TraceID         string                   `thrift:"trace_id,1,required" frugal:"1,required,string" form:"trace_id,required" json:"trace_id,required" query:"trace_id,required"`
    SpanID          string                   `thrift:"span_id,2,required" frugal:"2,required,string" form:"span_id,required" json:"span_id,required" query:"span_id,required"`
    ParentID        string                   `thrift:"parent_id,3,required" frugal:"3,required,string" form:"parent_id,required" json:"parent_id,required" query:"parent_id,required"`
    SpanName        string                   `thrift:"span_name,4,required" frugal:"4,required,string" form:"span_name,required" json:"span_name,required" query:"span_name,required"`
    SpanType        string                   `thrift:"span_type,5,required" frugal:"5,required,string" form:"span_type,required" json:"span_type,required" query:"span_type,required"`
    Type            SpanType                 `thrift:"type,6,required" frugal:"6,required,string" form:"type,required" json:"type,required" query:"type,required"`
    StartedAt       int64                    `thrift:"started_at,7,required" frugal:"7,required,i64" json:"started_at" form:"started_at,required" query:"started_at,required"`
    Duration        int64                    `thrift:"duration,8,required" frugal:"8,required,i64" json:"duration" form:"duration,required" query:"duration,required"`
    Status          SpanStatus               `thrift:"status,9,required" frugal:"9,required,string" form:"status,required" json:"status,required" query:"status,required"`
    StatusCode      int32                    `thrift:"status_code,10,required" frugal:"10,required,i32" form:"status_code,required" json:"status_code,required" query:"status_code,required"`
    Input           string                   `thrift:"input,11,required" frugal:"11,required,string" form:"input,required" json:"input,required" query:"input,required"`
    Output          string                   `thrift:"output,12,required" frugal:"12,required,string" form:"output,required" json:"output,required" query:"output,required"`
    LogicDeleteDate *int64                   `thrift:"logic_delete_date,13,optional" frugal:"13,optional,i64" json:"logic_delete_date" form:"logic_delete_date" query:"logic_delete_date"`
    ServiceName     *string                  `thrift:"service_name,14,optional" frugal:"14,optional,string" form:"service_name" json:"service_name,omitempty" query:"service_name"`
    Logid           *string                  `thrift:"logid,15,optional" frugal:"15,optional,string" form:"logid" json:"logid,omitempty" query:"logid"`
    CustomTags      map[string]string        `thrift:"custom_tags,101,optional" frugal:"101,optional,map<string:string>" form:"custom_tags" json:"custom_tags,omitempty" query:"custom_tags"`
    AttrTos         *AttrTos                 `thrift:"attr_tos,102,optional" frugal:"102,optional,AttrTos" form:"attr_tos" json:"attr_tos,omitempty" query:"attr_tos"`
    SystemTags      map[string]string        `thrift:"system_tags,103,optional" frugal:"103,optional,map<string:string>" form:"system_tags" json:"system_tags,omitempty" query:"system_tags"`
    Annotations     []*annotation.Annotation `thrift:"annotations,104,optional" frugal:"104,optional,list<annotation.Annotation>" form:"annotations" json:"annotations,omitempty" query:"annotations"`
}

typedef string SpanType (ts.enum="true")
const SpanType SpanType_Unknown = "unknwon"
const SpanType SpanType_Prompt = "prompt"
const SpanType SpanType_Model = "model"
const SpanType SpanType_Parser = "parser"
const SpanType SpanType_Embedding = "embedding"
const SpanType SpanType_Memory = "memory"
const SpanType SpanType_Plugin = "plugin"
const SpanType SpanType_Function = "function"
const SpanType SpanType_Graph = "graph"
const SpanType SpanType_Remote = "remote"
const SpanType SpanType_Loader = "loader"
const SpanType SpanType_Transformer = "transformer"
const SpanType SpanType_VectorStore = "vector_store"
const SpanType SpanType_VectorRetriever= "vector_retriever"
const SpanType SpanType_Agent = "agent"
const SpanType SpanType_LLMCall = "LLMCall"

typedef string SpanStatus (ts.enum="true")
const SpanStatus SpanStatus_Success = "success"
const SpanStatus SpanStatus_Error = "error"
const SpanStatus SpanStatus_Broken = "broken"

struct AttrTos {
    1: optional string input_data_url
    2: optional string output_data_url
    3: optional map<string, string> multimodal_data
}

示例

请求示例

curl --location 'https://api.coze.cn/v1/loop/spans/search' \
--header 'Bearer {实际token}' \
--header 'Content-Type: application/json' \
--header 'agw-js-conv: str' \
--data '{
    "workspace_id": {实际空间id},
    "platform_type": "coze_project",
    "span_list_type": "all_span",
    "filters": {
        "filter_fields": [
            {
                "field_name": "trace_id",
                "field_type": "string",
                "values": ["29a2cfed1e409cb765e5b4f0632eb42c"],
                "query_type": "eq"
            }
        ]
    },
    "start_time": 1754156936208,
    "end_time": 1756221000000,
    "page_size": 1,
    "order_bys": [
        {
            "field": "start_time",
            "is_asc": true
        }
    ]
}'

返回示例

{
    "code": 0,
    "msg": "",
    "data": {
        "has_more": false,
        "next_page_token": "eyJTdGFydFRpbWUiOjE3NTYwOTUwMDAwMDAwMDAsIlNwYW5JRCI6IjEyMzQ1Njc4MTIzNDU2OTUifQ==",
        "spans": [
            {
                "started_at": "1755497400000",
                "system_tags": {
                    "create_time": "1756111796259278"
                },
                "output": "test",
                "input": "test",
                "logid": "xxx",
                "parent_id": "0",
                "type": "unknwon",
                "duration": "0",
                "span_name": "",
                "span_type": "",
                "trace_id": "xxx",
                "logic_delete_date": "1758703796259",
                "span_id": "xxx",
                "status": "success",
                "status_code": 0,
                "custom_tags": {
                    "input_tokens": "20",
                    "output_tokens": "10",
                    "tokens": "30",
                    "bot_id": "xx",
                    "fornax_space_id": "xxx"
                }
            }
        ]
    }
}

错误码

错误码	错误信息	说明
`600904002`	`invalid param`	参数校验错误。通常是时间范围、`page_size` 等参数不合法。
`600904004`	`internal error`	内部错误，可联系扣子罗盘排查。
`600903208`	`the trace has expired`	该 trace 已过期。
`600900101`	`no access permission`	没有权限。通常是没有对应空间权限。
`600900205`	`request is limited`	限流。

文档对您有帮助吗?