# 预览触发时间 (/docs/api/native/automation/previewTriggerSchedule)





校验规则与时区并预览未来触发时间。返回人读说明及最多五个未来时间，不会创建触发器或运行。

`POST /automation/v1/triggers/preview`

## 鉴权 [#鉴权]

`Authorization: Bearer $PRAXIS_API_KEY`

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

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| header: Accept-Language | `string` | 可选；人读描述的语言，支持中文（默认）与英文，按语言权重选择。 |

### application/json [#applicationjson]

不接受额外字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| schedule | `object` / `object` / `object` | 必填 / 必有；三选一：cron 为五段表达式（支持 L/W/#）；every 至少一分钟；at 为带时区的一次性时间。与创建使用相同校验：at 须在当前时间至一年后之间；every 须为正整数毫秒且不超过 366 天。 |
| schedule（分支1).cron | `string` | 必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule（分支2).every | `string` / `object` | 必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。 |
| schedule（分支2).every（分支2).days | `integer` | 可选；天数，非负整数。 minimum: 0 |
| schedule（分支2).every（分支2).hours | `integer` | 可选；小时数，非负整数。 minimum: 0 |
| schedule（分支2).every（分支2).minutes | `integer` | 可选；分钟数，非负整数。 minimum: 0 |
| schedule（分支2).every（分支2).seconds | `integer` | 可选；秒数，非负整数。 minimum: 0 |
| schedule（分支2).every（分支2).milliseconds | `integer` | 可选；毫秒数，非负整数。 minimum: 0 |
| schedule（分支3).at | `string` | 必填 / 必有；一次性触发时刻，需带 Z 或 ±HH:MM 时区；必须在请求时刻至一年后之间。调用时将示例替换为该范围内的未来时间。 pattern: "(Z\|[+-]\\d\\d:\\d\\d)$"；format: "date-time" |
| timezone | `string` | 可选；IANA 时区，默认 UTC；夏令时跳过不存在的时刻，重复时刻只触发一次。 |

## 示例 [#示例]

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

```bash
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers/preview" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "schedule": {
    "cron": "0 9 * * *"
  },
  "timezone": "UTC"
}'
```

```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.preview({
  "body": {
    "schedule": {
      "cron": "0 9 * * *"
    },
    "timezone": "UTC"
  }
});
console.log(result);
```

## 响应 [#响应]

### HTTP 200 [#http-200]

Success

`application/json`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| description | `string` | 必填 / 必有；规则的人读描述；常见 cron 为自然语言，其余回显表达式。语言由 Accept-Language 决定，默认中文。 |
| next_fire_times | `string[]` | 必填 / 必有；按该规则和时区计算的接下来最多 5 次触发时间（RFC 3339 UTC）。 maxItems: 5 |

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

HTTP 200

```json
{
  "description": "每天 09:00 · UTC",
  "next_fire_times": [
    "2026-10-13T09:00:00.000Z",
    "2026-10-14T09:00:00.000Z",
    "2026-10-15T09:00:00.000Z",
    "2026-10-16T09:00:00.000Z",
    "2026-10-17T09:00:00.000Z"
  ]
}
```

## 错误码 [#错误码]

| HTTP | 错误码与说明 |
| --- | --- |
| 400 | INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 SCHEDULE_INVALID：定时规则或时间边界无效。 TIMEZONE_INVALID：时区不是有效的 IANA 时区。 INTERVAL_TOO_SHORT：定时间隔短于一分钟。 |
| default | RFC 9457 automation problem. 429 includes Retry-After. |

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