> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

查询 Trace 列表。
## 基础信息 {#0811efb3}
<!-- @cols-width: 220,520 -->
| | | \
|请求方式 |`POST` |
|---|---|
| | | \
|请求地址 |`https://api.coze.cn/v1/loop/spans/search` |
| | | \
|权限 |`listLoopTrace` |\
| |确保调用该接口使用的访问令牌开通了 `listLoopTrace` 权限，详细信息参考[鉴权方式](https://docs.coze.cn/developer_guides/authentication)。 |
| | | \
|QPS 限制 |每个空间每秒最多调用 1 次。 |

## 请求参数 {#6b9e8966}
### Header {#079bc45e}
<!-- @cols-width: 180,150,100,180,390 -->
| | | | | | \
|参数 |类型/取值 |是否必选 |示例 |说明 |
|---|---|---|---|---|
| | | | | | \
|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 {#5a9d80c5}
<!-- @cols-width: 180,150,100,180,432 -->
| | | | | | \
|参数 |类型 |是否必选 |示例 |说明 |
|---|---|---|---|---|
| | | | | | \
|workspace_id |String |必选 |`{实际空间id}` |扣子罗盘空间 ID。详细获取方式参考 [获取扣子罗盘空间 ID](https://loop.coze.cn/open/docs/cozeloop/get_workspace_id_and_token#01dede13)。  |
| | | | | | \
|start_time |String |必选 |`1754156936208` |开始时间（毫秒）。 |
| | | | | | \
|end_time |String |必选 |`1756221000000` |结束时间（毫秒）。 |
| | | | | | \
|filters |Object |可选 |\- |查询条件组。详见 [filters Object](/cozeloop/km5xh834#6fa28b1d)。 |
| | | | | | \
|page_size |i32 |可选 |`1` |分页大小，最大 200，默认 100。 |
| | | | | | \
|page_token |String |可选 |\- |下一页的游标，从返回结果获取。 |
| | | | | | \
|order_bys |Array |可选 |\- |排序（只支持 `start_time` 的倒排）。详见 [order_bys Object](/cozeloop/km5xh834#d30e88be)。 |
| | | | | | \
|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 {#6fa28b1d}
<!-- @cols-width: 220,140,100,288,488 -->
| | | | | | \
|参数 |类型 |是否必选 |示例 |说明 |
|---|---|---|---|---|
| | | | | | \
|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 {#d30e88be}
<!-- @cols-width: 220,140,100,170,370 -->
| | | | | | \
|参数 |类型 |是否必选 |示例 |说明 |
|---|---|---|---|---|
| | | | | | \
|field |String |可选 |`start_time` |排序字段。 |
| | | | | | \
|is_asc |Bool |可选 |`false` |是否升序。 |

## 返回参数 {#c0a7bef5}
<!-- @cols-width: 220,150,500,390 -->
| | | | | \
|参数 |类型 |示例 |说明 |
|---|---|---|---|
| | | | | \
|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 结构参考 {#552b12b3}
```Thrift
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
}
```

## 示例 {#4d4ca3aa}
### 请求示例 {#8af8577c}
```Bash
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
        }
    ]
}'
```

### 返回示例 {#2d97c6d4}
```JSON
{
    "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"
                }
            }
        ]
    }
}
```


## 错误码 {#17f2e0c8}
<!-- @cols-width: 159,231,412 -->
| | | | \
|错误码 |错误信息 |说明 |
|---|---|---|
| | | | \
|`600904002` |`invalid param` |参数校验错误。通常是时间范围、`page_size` 等参数不合法。 |
| | | | \
|`600904004` |`internal error` |内部错误，可联系扣子罗盘排查。 |
| | | | \
|`600903208` |`the trace has expired` |该 trace 已过期。 |
| | | | \
|`600900101` |`no access permission` |没有权限。通常是没有对应空间权限。 |
| | | | \
|`600900205` |`request is limited` |限流。 |