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

# 按状态、类型与项目筛选列出训练任务

> 获取按状态、类型或项目筛选的训练任务列表。最多返回 100 个任务及最新进度快照。

PIN API 允许你列出账户中的所有训练任务。每个条目包含最新的训练进度、调度状态与超参数摘要，便于快速浏览工作负载的整体状态。

## 方法与路径

```http theme={null}
GET /v1/jobs
```

## 认证

在 `Authorization` 头中以 Bearer 令牌的形式携带你的 PIN API 令牌或 JWT。

```http theme={null}
Authorization: Bearer <token>
```

## 查询参数

<ParamField query="status" type="string" optional>
  按任务状态筛选。允许的值：`queued`、`running`、`paused`、`stopped`、`succeeded`、`failed`、`cancelled`、`intervening`。
</ParamField>

<ParamField query="type" type="string" optional>
  按训练类型筛选。允许的值：`sft`、`opd`、`pretrain`、`distill`、`qat`、`grpo`、`dpo`、`kto`、`orpo`、`simpo`、`ppo`。
</ParamField>

<ParamField query="project" type="string" optional>
  按项目或基座模型名称前缀筛选。
</ParamField>

## 请求示例

<CodeGroup>
  ```bash curl theme={null}
  curl -s "https://api.ariacompute.com/v1/jobs?status=running&type=sft" \
    -H "Authorization: Bearer $PIN_API_TOKEN"
  ```
</CodeGroup>

## 响应

返回标准的 PIN 成功信封，任务列表位于 `data.items` 下。

<ResponseField name="code" type="integer" required>
  成功为 `0`，出错为非零值。
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="属性">
    <ResponseField name="items" type="array" required>
      任务对象列表。

      <Expandable title="任务对象">
        <ResponseField name="job_id" type="string">
          唯一任务标识符（例如 `jb_...`）。
        </ResponseField>

        <ResponseField name="type" type="string">
          训练类型：`sft`、`opd`、`pretrain`、`distill`、`qat`、`grpo`、`dpo`、`kto`、`orpo`、`simpo`、`ppo`。
        </ResponseField>

        <ResponseField name="base_model" type="string">
          来自目录的基座模型名称。
        </ResponseField>

        <ResponseField name="teacher_model" type="string">
          用于 OPD 或蒸馏的冻结教师模型。
        </ResponseField>

        <ResponseField name="lora" type="object">
          LoRA/QLoRA/DoRA 配置。
        </ResponseField>

        <ResponseField name="hyperparams" type="object">
          训练超参数。
        </ResponseField>

        <ResponseField name="auto_intervention" type="object">
          若已启用，则为自动干预配置。
        </ResponseField>

        <ResponseField name="dataset_id" type="string">
          关联的数据集标识符。
        </ResponseField>

        <ResponseField name="status" type="string">
          当前任务状态。
        </ResponseField>

        <ResponseField name="dispatch_status" type="string">
          控制器调度状态。
        </ResponseField>

        <ResponseField name="agent_id" type="string">
          执行该任务的智能体 ID。
        </ResponseField>

        <ResponseField name="gpu_index" type="integer">
          分配给任务的 GPU 索引。
        </ResponseField>

        <ResponseField name="mlflow_run_id" type="string">
          MLflow 运行标识符。
        </ResponseField>

        <ResponseField name="mlflow_url" type="string">
          MLflow 运行的直接 URL。
        </ResponseField>

        <ResponseField name="error" type="string">
          最近一次错误消息（若有）。
        </ResponseField>

        <ResponseField name="progress" type="object">
          最新的步进指标。

          <Expandable title="属性">
            <ResponseField name="step" type="integer">
              训练步数。
            </ResponseField>

            <ResponseField name="loss" type="number">
              最新 loss 值。
            </ResponseField>

            <ResponseField name="reward" type="number">
              最新 reward 值（RL 任务）。
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 创建时间戳。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">
  可读消息（成功时为空）。
</ResponseField>

### 响应示例

```json theme={null}
{
  "code": 0,
  "data": {
    "items": [
      {
        "job_id": "jb_abc123def456",
        "type": "sft",
        "base_model": "meta-llama/Llama-3-8B",
        "lora": {
          "method": "lora",
          "rank": 16,
          "alpha": 32,
          "lora_dropout": 0.05,
          "target_modules": ["q_proj", "v_proj"],
          "quantization": "4bit_nf4"
        },
        "hyperparams": {
          "epochs": 3,
          "lr": 0.00002,
          "max_length": 2048
        },
        "dataset_id": "ds_xyz789",
        "status": "running",
        "dispatch_status": "running",
        "agent_id": "ag_node01_001",
        "gpu_index": 0,
        "progress": {
          "step": 1240,
          "loss": 0.8234
        },
        "created_at": "2025-01-15T09:23:17Z"
      }
    ]
  },
  "message": ""
}
```

## 错误

| Code | HTTP | 含义                |
| ---- | ---- | ----------------- |
| 401  | 401  | 缺失或无效的 Bearer 令牌。 |
| 500  | 500  | 内部服务器错误。          |

该接口最多返回 100 个任务，按 `created_at` 降序排列。