# 读取触发器 (/docs/api/native/automation/getTrigger)





读取规则、状态、未来触发时间与最近触发结果；ETag 可用于修改，完整 webhook URL 不会再次返回。

`GET /automation/v1/triggers/{id}`

## 鉴权 [#鉴权]

`Authorization: Bearer $PRAXIS_API_KEY`

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

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| path: id | `string` | 必填；触发器 ID（trg_）。 |

## 示例 [#示例]

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

先设置以下环境变量，使用你自己的资源：

| 变量 | 来源 |
| --- | --- |
| TRIGGER_ID | [触发器 id；webhook 调用前需恢复启用](/docs/api/native/automation/createTrigger) |

```bash
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

```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.triggers.retrieve({
  "path": {
    "id": env("TRIGGER_ID")
  }
});
console.log(result);
```

## 响应 [#响应]

### HTTP 200 [#http-200]

Success

| 响应头 | 类型 | 说明 |
| --- | --- | --- |
| ETag | `string` | Current resource revision for conditional updates. |

`application/json`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| name | `string` | 必填 / 必有；触发器名称，1–100 字符。 minLength: 1；maxLength: 100 |
| description | `string` | 必填 / 必有；触发器说明，最多 1000 字符。 maxLength: 1000 |
| labels | `object` | 必填 / 必有；触发器标签：字符串键值对，最多 64 个；键不能以保留前缀 praxis. 开头，违反返回 400 INPUT_INVALID。 |
| target | `string` | 必填 / 必有；要运行的脚本或工作流引用，形如 ns/name@标签或版本；默认跟随 latest，写成 @1.2.0 则钉死版本。 |
| input | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。 |
| input（分支5).* | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| input（分支6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| kind | `"schedule"` / `"webhook"` | 必填 / 必有；触发器类型。schedule 按计划（cron、every 或 at）触发；webhook 由入站 HTTP 请求触发。 |
| schedule | `object` / `object` / `object` / `null` | 必填 / 必有；定时规则，kind=schedule 时有值（cron、every 或 at 三选一）；webhook 为 null。 |
| schedule（分支1)（分支1).cron | `string` | 必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule（分支1)（分支2).every | `string` / `object` | 必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。 |
| schedule（分支1)（分支2).every（分支2).days | `integer` | 可选；天数，非负整数。 minimum: 0 |
| schedule（分支1)（分支2).every（分支2).hours | `integer` | 可选；小时数，非负整数。 minimum: 0 |
| schedule（分支1)（分支2).every（分支2).minutes | `integer` | 可选；分钟数，非负整数。 minimum: 0 |
| schedule（分支1)（分支2).every（分支2).seconds | `integer` | 可选；秒数，非负整数。 minimum: 0 |
| schedule（分支1)（分支2).every（分支2).milliseconds | `integer` | 可选；毫秒数，非负整数。 minimum: 0 |
| schedule（分支1)（分支3).at | `string` | 必填 / 必有；一次性触发的时刻（RFC 3339 UTC）；不能早于当前时间，也不能晚于一年后。执行后触发器进入 expired。 format: "date-time" |
| timezone | `string` | 必填 / 必有；IANA 时区名，定时规则按它解释；API 缺省为 UTC。 default: "UTC" |
| start_at | `string` / `null` | 必填 / 必有；定时触发器的开始时间（RFC 3339 UTC）；此前不触发。没有限制为 null。 |
| end_at | `string` / `null` | 必填 / 必有；定时触发器的结束时间（RFC 3339 UTC）；超过后进入 expired。没有期限为 null。 |
| overlap | `"skip"` / `"allow"` | 必填 / 必有；重叠策略：上一次运行未结束时又到点，skip（默认）跳过，allow 照常启动。 default: "skip" |
| catchup_window_seconds | `integer` | 必填 / 必有；补跑窗口（秒），默认 300，仅定时触发器适用：到点时若已延迟超过该值（宕机、暂停期间），记为 missed 且不补跑。 default: 300；minimum: 0 |
| webhook | `object` / `null` | 必填 / 必有；webhook 设置，kind=webhook 时有值；schedule 触发器为 null。 |
| webhook（分支1).input_mode | `"body"` / `"envelope"` | 必填 / 必有；webhook 触发时传给目标的输入形态。body（默认）只传请求体；envelope 传含 body、raw_body、raw_body_encoding、headers、webhook_id、received_at 的信封对象。 |
| webhook（分支1).url_hint | `string` | 必填 / 必有；webhook 地址的掩码提示，省略号代替私密 token，不能用于调用。新建触发器为公开完整 URL；历史记录可能为 /automation/v1/hooks/{id}/… 相对路径。 |
| id | `string` | 必填 / 必有；触发器 ID，前缀 trg_；用于 webhook 地址以及触发器的所有接口。 |
| owner | `string` | 必填 / 必有；所属租户，由网关注入；按不透明字符串处理。 |
| state | `"enabled"` / `"paused"` / `"expired"` | 必填 / 必有；触发器状态。enabled 启用，会按计划或请求触发；paused 已暂停，不触发；expired 已到期，一次性触发器执行完或超过 end_at 后进入，不再触发。 |
| source | `"api"` / `"definition"` | 必填 / 必有；触发器来源。api 为通过 API 创建，可修改和删除；definition 为由工作流 YAML 的 schedule 生成，只能暂停或恢复，修改返回 409 TRIGGER_MANAGED。 |
| created_by | `object` | 必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。 |
| created_by.type | `"user"` / `"api_key"` / `"agent"` / `"run"` / `"trigger"` | 必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。 |
| created_by.id | `string` | 必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。 |
| created_by_user_id | `string` | 必填 / 必有；创建者的真实用户 ID，由网关转发；触发器启动的运行以该用户身份取令牌，用于审计与用量归属。 |
| next_fire_times | `string[]` | 必填 / 必有；接下来最多 5 次的触发时间（RFC 3339 UTC）；webhook、已暂停或已到期的触发器为空数组。 maxItems: 5 |
| last_firing | `object` / `null` | 必填 / 必有；最近一次触发记录；从未触发为 null。 |
| last_firing（分支1).id | `string` | 必填 / 必有；触发记录 ID；记录保留 30 天。 |
| last_firing（分支1).trigger_id | `string` | 必填 / 必有；所属触发器 ID（trg_ 前缀）。 |
| last_firing（分支1).scheduled_at | `string` | 必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time" |
| last_firing（分支1).fired_at | `string` | 必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time" |
| last_firing（分支1).outcome | `"accepted"` / `"started"` / `"skipped_overlap"` / `"missed"` / `"failed"` / `"deduped"` | 必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。 |
| last_firing（分支1).run_id | `string` / `null` | 必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。 |
| last_firing（分支1).resolved_version | `string` / `null` | 必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。 |
| last_firing（分支1).error | `object` / `null` | 必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。 |
| last_firing（分支1).error（分支1).code | `string` | 必填 / 必有；失败的错误码。 |
| last_firing（分支1).error（分支1).message | `string` | 必填 / 必有；失败的说明文字。 |
| counts | `object` | 必填 / 必有；触发结果累计次数 {started, skipped, missed, failed}。 不接受额外字段。 |
| counts.started | `integer` | 必填 / 必有；成功启动运行的次数。 minimum: 0 |
| counts.skipped | `integer` | 必填 / 必有；因重叠策略为 skip 且上一次运行未结束而跳过的次数。 minimum: 0 |
| counts.missed | `integer` | 必填 / 必有；因延迟超过补跑窗口而错过的次数。 minimum: 0 |
| counts.failed | `integer` | 必填 / 必有；创建运行失败的次数。 minimum: 0 |
| created_at | `string` | 必填 / 必有；创建时间（RFC 3339 UTC）。 format: "date-time" |
| updated_at | `string` | 必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。 format: "date-time" |
| etag | `string` | 必填 / 必有；触发器当前修订标识，更新时作为 If-Match；不匹配返回 412。 |
| usage_30d | `object` / `null` | 可选；仅 GET /triggers/{id} 返回，列表省略。最近 30 天由此触发器启动的运行及子运行的归因实扣。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。 |
| usage_30d（分支1).currency | `"USD"` | 必填 / 必有；金额币种，固定为 USD。 |
| usage_30d（分支1).cost | `string` | 必填 / 必有；已评级实扣的美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\\.[0-9]{6}$" |
| usage_30d（分支1).pending_events | `integer` | 必填 / 必有；尚未评级的用量事件数，金额稍后才计入。 minimum: 0 |

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

HTTP 200

```json
{
  "id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
  "owner": "tnt_3a9759864ccb4e00",
  "name": "sample-webhook-1791867412840-b05e8a",
  "description": "",
  "labels": {
    "namespace": "docs-samples"
  },
  "target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
  "input": {},
  "kind": "webhook",
  "schedule": null,
  "timezone": "UTC",
  "start_at": null,
  "end_at": null,
  "overlap": "skip",
  "catchup_window_seconds": 300,
  "webhook": {
    "input_mode": "body",
    "url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
  },
  "state": "paused",
  "source": "api",
  "created_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "created_by_user_id": "usr_49d4fcb99517",
  "next_fire_times": [],
  "last_firing": null,
  "counts": {
    "started": 0,
    "skipped": 0,
    "missed": 0,
    "failed": 0
  },
  "created_at": "2026-10-13T04:58:09.974Z",
  "updated_at": "2026-10-13T04:58:12.519Z",
  "etag": "etag_00mv67n1yf40e7b8d39ce5459d9ce835bfb1083701",
  "usage_30d": null
}
```

## 错误码 [#错误码]

| HTTP | 错误码与说明 |
| --- | --- |
| 400 | INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 |
| 404 | TRIGGER_NOT_FOUND：触发器不存在或不可访问，回调鉴权失败也使用此错误。 |
| default | RFC 9457 automation problem. 429 includes Retry-After. |

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