# 列出动作 (/docs/api/native/automation/listActions)





筛选可见动作并读取修订摘要。可按名称或说明筛选，包含近七天统计；不含实现源码，默认排除已归档动作。

`GET /automation/v1/actions`

## 鉴权 [#鉴权]

`Authorization: Bearer $PRAXIS_API_KEY`

## 请求字段 [#请求字段]

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| query: limit | `integer` | 可选；每页条数，整数 1–100，默认 20。 minimum: 1；maximum: 100 |
| query: cursor | `string` | 可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。 |
| query: q | `string` | 可选；不区分大小写，按名称或说明的字面子串匹配；% 与 _ 无通配含义。 |
| query: namespace | `string[]` | 可选；仅返回指定命名空间的定义，名称按小写匹配。 多个值以逗号分隔，匹配任一值。 minItems: 1 |
| query: scope | `"platform"` / `"own"[]` | 可选；platform 仅平台定义，own 仅租户自建定义；省略返回两者。 多个值以逗号分隔，匹配任一值。 minItems: 1 |
| query: archived | `boolean` | 可选；true 仅已归档，false 仅未归档；默认 false。 |
| query: implementation | `"code"` / `"container"` / `"shell"[]` | 可选；按实现类型筛选：code、container 或 shell；省略不过滤。 多个值以逗号分隔，匹配任一值。 minItems: 1 |
| query: labels | `object` | 可选；按标签过滤，使用 labels[k]=v；同键逗号多值取任一，不同键同时满足。 |
| query: created_at[gte] | `string` | 可选；创建时间下界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time" |
| query: created_at[lte] | `string` | 可选；创建时间上界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time" |

## 示例 [#示例]

[SDK 安装与示例环境](/docs/api/native/automation)

```bash
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  --get \
  --data-urlencode "namespace=docs-samples" \
  --data-urlencode "limit=1"
```

```typescript
import { createAutomationClient } from '@deepractice-ai/praxis-sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.list({
  "query": {
    "namespace": [
      "docs-samples"
    ],
    "limit": 1
  }
});
console.log(result);
```

## 响应 [#响应]

### HTTP 200 [#http-200]

Success

`application/json`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data | `object[]` | 必填 / 必有；本页的动作（含当前修订摘要与近七天统计），按 created_at 倒序、id 倒序排列。 |
| data[].id | `string` | 必填 / 必有；动作 ID，前缀 act_；日常调用使用 namespace 与 name，而不是 id。 |
| data[].namespace | `string` | 必填 / 必有；动作命名空间；平台动作为 praxis，裸名引用解析到 praxis。 |
| data[].name | `string` | 必填 / 必有；动作名，与 namespace 一起唯一标识动作；小写字母、数字、点、下划线、连字符，最长 64 字符。 |
| data[].description | `string` | 必填 / 必有；动作说明，最多 1000 字符。 |
| data[].labels | `object` | 必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。 |
| data[].owner | `string` | 必填 / 必有；动作所属租户，由网关注入；按不透明字符串处理。 |
| data[].builtin | `boolean` | 必填 / 必有；true 表示平台内置动作（命名空间 praxis）；用户创建的动作为 false。 |
| data[].stats_7d | `object` | 必填 / 必有；近七天统计；平台动作按调用方租户隔离，只反映当前调用方的调用，不是平台全局统计。 不接受额外字段。 |
| data[].stats_7d.calls | `number` | 必填 / 必有；近七天内对该动作的调用次数，按小时汇总。 |
| data[].stats_7d.failures | `number` | 必填 / 必有；近七天内失败的调用次数。 |
| data[].stats_7d.p50_ms | `null` / `number` | 必填 / 必有；耗时中位数的近似上界，单位毫秒；正耗时向上归入 2 的幂分桶（9 ms → 16 ms），0 独立一桶；无有效耗时样本时为 null。 |
| data[].dependents | `object` | 必填 / 必有；引用该动作的脚本与工作流数量，口径为最新版本加草稿。 不接受额外字段。 |
| data[].dependents.scripts | `number` | 必填 / 必有；引用该动作的脚本数量。 |
| data[].dependents.workflows | `number` | 必填 / 必有；引用该动作的工作流数量。 |
| data[].archived_at | `null` / `string` | 必填 / 必有；归档时间；未归档为 null。归档后名字保留，不能复用。 |
| data[].created_at | `string` | 必填 / 必有；创建时间（RFC 3339 UTC）。 |
| data[].updated_at | `string` | 必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。 |
| data[].current_revision | `object` | 必填 / 必有；列表使用的修订摘要：只含契约与运行位置，不含实现源码。 不接受额外字段。 |
| data[].current_revision.id | `string` | 必填 / 必有；修订 ID，前缀 actr_。 |
| data[].current_revision.implementation | `object` | 必填 / 必有；动作列表只返回 {kind, host}，不含源码；动作详情返回完整 implementation。 不接受额外字段。 |
| data[].current_revision.implementation.kind | `"code"` / `"container"` / `"shell"` | 必填 / 必有；动作实现方式。code 为源码实现（目前仅 language=ts 可用）；container 为容器镜像加命令，暂未开放；shell 为 shell 脚本，暂未开放。 |
| data[].current_revision.implementation.host | `"builtin"` / `"isolate"` / `"sandbox"` | 必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。 |
| data[].current_revision.host | `"builtin"` / `"isolate"` / `"sandbox"` | 必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。 |
| data[].current_revision.input_schema | `object` | 必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。 |
| data[].current_revision.input_schema.*（分支5) | `object` | 递归 JSON 值。 |
| data[].current_revision.input_schema.*（分支6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| data[].current_revision.output_schema | `object` | 必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。 |
| data[].current_revision.output_schema.*（分支5) | `object` | 递归 JSON 值。 |
| data[].current_revision.output_schema.*（分支6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| data[].current_revision.created_at | `string` | 必填 / 必有；该修订的创建时间（RFC 3339 UTC）。 |
| next_cursor | `null` / `string` | 必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。 |

### 实测响应 [#实测响应]

HTTP 200

```json
{
  "data": [
    {
      "id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
      "owner": "tnt_3a9759864ccb4e00",
      "namespace": "docs-samples",
      "name": "sample-action-1791867412840-b05e8a",
      "description": "",
      "labels": {},
      "builtin": false,
      "archived_at": null,
      "created_at": "2026-10-13T04:57:09.039Z",
      "updated_at": "2026-10-13T04:57:09.039Z",
      "current_revision": {
        "id": "actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
        "implementation": {
          "kind": "code",
          "host": "isolate"
        },
        "host": "isolate",
        "input_schema": {
          "type": "object",
          "properties": {
            "n": {
              "type": "number"
            }
          },
          "required": [
            "n"
          ],
          "additionalProperties": false
        },
        "output_schema": {
          "type": "object",
          "properties": {
            "answer": {
              "type": "number"
            }
          },
          "required": [
            "answer"
          ],
          "additionalProperties": false
        },
        "created_at": "2026-10-13T04:57:09.039Z"
      },
      "stats_7d": {
        "calls": 0,
        "failures": 0,
        "p50_ms": null
      },
      "dependents": {
        "scripts": 0,
        "workflows": 0
      }
    }
  ],
  "next_cursor": null
}
```

## 错误码 [#错误码]

| HTTP | 错误码与说明 |
| --- | --- |
| 400 | INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 |
| default | RFC 9457 automation problem. 429 includes Retry-After. |

[鉴权错误与通用错误](/docs/api/errors) · 排查时保留响应头 `X-Request-Id`。