<span id="查询指定自动化任务的运行历史"></span>

# List runs for an automation task

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Read runs for a task definition, then use returned run IDs to retrieve details, events, and results.

```text
GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-automation-tasks/{automation_task_id}/runs
```

<span id="请求参数"></span>

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl --get "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agent-automation-tasks/$AUTOMATION_TASK_ID/runs" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "limit=50" --data-urlencode "offset=0"
```

:::::
:::::{tab-item} Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | string | Yes | A personal access token valid in the current environment; workspace access is also required. |
| `X-Workspace-ID` | string | Yes | Must match path workspace_id. |
| `workspace_id` | string | Yes | Workspace ID; do not mix identifiers from other environments. |
| `status` | string | No | One of eight run states. Omission does not filter by state. |
| `created_from` | string | No | RFC 3339 timestamp, inclusive start. |
| `created_to` | string | No | RFC 3339 timestamp, exclusive end. |
| `limit` | integer | No | Default 50, maximum 200. Paginate using the returned limit. |
| `offset` | integer | No | Default 0; negative values become 0. |
| `automation_task_id` | string | Yes | Automation task definition ID, not a run ID. |

:::::
::::::
:::::::

<span id="返回结果"></span>

## Results

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "run-example",
        "workspace_id": "workspace-example",
        "automation_task_id": "task-example",
        "automation_task_version": 1,
        "trigger_type": "manual",
        "trigger_config_snapshot": {
          "mode": "cron",
          "cron_expression": "TZ=UTC 0 9 * * *"
        },
        "status": "queued",
        "created_at": "2026-11-11T01:00:00Z",
        "updated_at": "2026-11-11T01:00:00Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | 0 on success. |
| `data.items` | object[] | Run records on this page; [] when empty. See [run objects](run-objects.md) for fields. |
| `data.total` | integer | Total records matching the current filters, not the number on this page. |
| `data.limit` | integer | Effective page size. |
| `data.offset` | integer | Effective offset. |

:::::
::::::
:::::::

<span id="查询范围与分页"></span>

## Query scope and pagination

Sorts by created_at descending, then id ascending for ties. Fetch the next page with returned offset+limit. Stop at total or an empty page. Concurrent insertions or state changes may cause duplicates or omissions in offset pagination; it is not a snapshot cursor. Use run IDs for details/events/results, and automation_task_id for task definitions.

A valid task ID with no matching runs can return an empty list. This entry point does not first read the parent task, so a 200 empty list does not prove that the parent exists.

See [query rules](query-rules.md) for parameter normalization and time boundaries, and [errors and environments](errors-environments.md) for error and authentication layers. SDK/CLI clients offer general resource invocation. The lack of a dedicated list method does not imply an unavailable capability.
