# 获取批量推理任务列表
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
`POST https://ark.cn-beijing.volcengineapi.com/?Action=ListBatchInferenceJobs&Version=2024-01-01`
获取批量推理任务列表。支持按标签、任务状态、模型等条件筛选，并支持分页和排序。
> **说明**
>
> 支持按标签（*TagFilters*）、任务属性（*Filter*）筛选，并通过 *PageNumber* / *PageSize* 分页。排序字段支持 `CreateTime` / `UpdateTime`，排序顺序支持 `Asc` / `Desc`。
## 鉴权
本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。
* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。
---
## 请求参数
### Body 参数
**Filter** `object` | 属性筛选
按任务属性筛选的条件组。
**CustomModelIds** `string[]` | 定制模型筛选
`Filter.CustomModelIds`
按定制模型 ID 列表筛选。
**FoundationModels** `object[]` | 基础模型筛选
`Filter.FoundationModels`
按基础模型名称及版本筛选。
**Name** `string` `必选` | 模型名称
`Filter.FoundationModels.Name`
基础模型名称，例如 `doubao-seed-2-1-pro-260628`。
**ModelVersions** `string[]` | 版本号列表
`Filter.FoundationModels.ModelVersions`
基础模型版本号列表。
**Ids** `string[]` | 任务 ID 列表
`Filter.Ids`
指定要查询的批量推理任务 ID 列表。
**Name** `string` | 名称模糊匹配
`Filter.Name`
按任务名称做模糊搜索。
**Phases** `string[]` | 状态筛选
`Filter.Phases`
按任务状态筛选。可选值：`Queued`、`Running`、`Completed`、`Terminating`、`Terminated`、`Failed`。
**PageNumber** `integer` `默认值 1` | 起始页码
分页查询的起始页码，从 1 开始。
**PageSize** `integer` `默认值 10` | 每页条数
分页查询时每页返回的记录数。
**取值范围**：`[1, 100]`
**ProjectName** `string` `默认值 default` | 项目名称
资源所属的项目名称。若资源不在默认项目中，需填写正确的项目名称。
**SortBy** `string` | 排序字段
排序字段。可选值：`CreateTime`、`UpdateTime`。
**SortOrder** `string` | 排序顺序
排序顺序。可选值：`Asc`、`Desc`。
**TagFilters** `object[]` | 标签筛选
按任务绑定的标签筛选。
**Key** `string` `必选` | 标签键
`TagFilters.Key`
标签键，必填。
**Values** `string[]` | 标签值列表
`TagFilters.Values`
## 响应参数
**Items** `object[]` | 任务列表
批量推理任务列表。
**CreateTime** `string` | 创建时间
`Items.CreateTime`
任务创建时间，RFC 3339 格式。
**Description** `string` | 任务描述
`Items.Description`
批量推理任务的描述信息。
**Id** `string` | 任务 ID
`Items.Id`
批量推理任务的唯一 ID。
**InputFileTosLocation** `object` | 输入文件
`Items.InputFileTosLocation`
批量推理输入文件的 TOS 位置。
**BucketName** `string` | TOS 桶名称
`Items.InputFileTosLocation.BucketName`
TOS 桶名称。当前火山方舟仅支持华北 2-北京地域（`cn-beijing`）的 TOS 桶。
**ObjectKey** `string` | 对象路径
`Items.InputFileTosLocation.ObjectKey`
TOS 对象路径。输入为 JSONL 文件的完整 object key；输出文件夹路径建议以 `/` 结尾。
**ModelReference** `object` | 模型引用
`Items.ModelReference`
任务使用的模型引用。
**CustomModelId** `string` | 定制模型 ID
`Items.ModelReference.CustomModelId`
定制模型 ID。与 *FoundationModel* 二选一，仅需指定其一。
**FoundationModel** `object` | 基础模型引用
`Items.ModelReference.FoundationModel`
基础模型引用对象。与 *CustomModelId* 二选一，仅需指定其一。
**ModelVersion** `string` | 模型版本
`Items.ModelReference.FoundationModel.ModelVersion`
基础模型版本号，例如 `240615`。
**Name** `string` | 模型名称
`Items.ModelReference.FoundationModel.Name`
基础模型名称，例如 `doubao-seed-2-1-pro-260628`。
**Name** `string` | 任务名称
`Items.Name`
批量推理任务名称。
**OutputDirTosLocation** `object` | 输出文件夹
`Items.OutputDirTosLocation`
批量推理任务结果输出的 TOS 文件夹位置。
**BucketName** `string` | TOS 桶名称
`Items.OutputDirTosLocation.BucketName`
TOS 桶名称。当前火山方舟仅支持华北 2-北京地域（`cn-beijing`）的 TOS 桶。
**ObjectKey** `string` | 对象路径
`Items.OutputDirTosLocation.ObjectKey`
TOS 对象路径。输入为 JSONL 文件的完整 object key；输出文件夹路径建议以 `/` 结尾。
**ProjectName** `string` | 项目名称
`Items.ProjectName`
资源所属的项目名称。
**RequestCounts** `object` | 请求数量
`Items.RequestCounts`
任务的请求数量统计。
**Completed** `number` | 完成数
`Items.RequestCounts.Completed`
已成功完成的请求数。
**Failed** `number` | 失败数
`Items.RequestCounts.Failed`
失败的请求数。
**Total** `number` | 请求总数
`Items.RequestCounts.Total`
任务包含的请求总数。
**Tags** `object[]` | 任务标签
`Items.Tags`
任务绑定的标签列表。
**Key** `string` | 标签键
`Items.Tags.Key`
**Value** `string` | 标签值
`Items.Tags.Value`
**UpdateTime** `string` | 更新时间
`Items.UpdateTime`
任务最近更新时间，RFC 3339 格式。
**CompletionWindow** `string` | 最大等待时间
`Items.CompletionWindow`
任务的最大等待时间，超过该时间任务仍未完成则自动终止。
**ExpireTime** `string` | 到期时间
`Items.ExpireTime`
任务到期时间，RFC 3339 格式。
**Status** `object` | 任务状态
`Items.Status`
任务的状态元信息。
**Phase** `string` | 任务状态
`Items.Status.Phase`
批量推理任务当前所处阶段。各状态含义如下：
- `Queued`：排队中，因账号下并发任务数达到上限等原因等待调度。
- `Initializing`：初始化中。
- `Running`：运行中。
- `Terminating`：取消中（到期、系统原因或手动终止触发）。
- `Terminated`：已终止。
- `Completed`：已完成，所有请求均已处理完毕。
- `Failed`：失败，通常由输入文件校验失败等原因导致。
**PhaseTime** `string` | 状态更新时间
`Items.Status.PhaseTime`
当前状态的更新时间，RFC 3339 格式。
**Message** `string` | 状态描述
`Items.Status.Message`
当前状态的描述信息，用于补充说明任务进度或失败原因。
**PageNumber** `integer` | 页码
当前返回结果对应的页码。
**PageSize** `integer` | 每页条数
当前返回结果对应的每页记录数。
**TotalCount** `integer` | 任务总数
当前筛选条件下符合条件的任务总数。
## 代码示例
## 默认
### cURL
#### Request
```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=ListBatchInferenceJobs&Version=2024-01-01' \
-H 'Content-Type: application/json' \
-H 'X-Date: ' \
-H 'X-Content-Sha256: ' \
-H 'Authorization: HMAC-SHA256 Credential=//cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=' \
-d '{
"ProjectName": "default",
"PageNumber": 1,
"PageSize": 10,
"SortOrder": "Desc",
"SortBy": "CreateTime",
"TagFilters": [
{
"Key": "owner",
"Values": [
"team-a"
]
}
],
"Filter": {
"Ids": [
"bi-20240918194641-r2nwq"
],
"Name": "批量推理任务",
"FoundationModels": [
{
"Name": "doubao-seed-2-0-pro",
"ModelVersions": ["260215"]
}
],
"CustomModelIds": [],
"Phases": [
"Completed"
]
}
}
'
```
#### Response
```
{
"ResponseMetadata": {
"RequestId": "2024091819503335D2321703C1A3CCA3",
"Action": "ListBatchInferenceJobs",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"TotalCount": 1,
"PageNumber": 1,
"PageSize": 10,
"Items": [
{
"Id": "bi-20240918194641-r2nwq",
"Name": "批量推理任务",
"Description": "这是一个批量推理任务",
"InputFileTosLocation": {
"BucketName": "my-bucket-name",
"ObjectKey": "batch-inference-job/dataset/my-job.jsonl"
},
"OutputDirTosLocation": {
"BucketName": "my-bucket-name",
"ObjectKey": "batch-inference-job/output/"
},
"CompletionWindow": "1d",
"Status": {
"Phase": "Completed",
"PhaseTime": "2024-09-18T11:50:00Z",
"Message": "批量推理任务已完成"
},
"ModelReference": {
"FoundationModel": {
"Name": "doubao-seed-2-0-pro",
"ModelVersion": "260215"
}
},
"RequestCounts": {
"Total": 2,
"Completed": 2,
"Failed": 0
},
"Tags": [
{
"Key": "owner",
"Value": "team-a"
},
{
"Key": "test_key",
"Value": "test_value"
}
],
"ProjectName": "default",
"CreateTime": "2024-09-18T11:46:41Z",
"UpdateTime": "2024-09-18T11:50:00Z",
"ExpireTime": "2024-09-19T11:46:41Z"
}
]
}
}
```