# 定期运行

定期运行让一个现成工具、一个动作或一个平台独有接口每天或每周在你所在时区的固定时间跑一次，只交付上一次之后的新内容。每次都是一次普通调用，结束时结算；超过上限的那一次跳过、不扣费。可以用 Key、在控制台，或直接让 AI 应用“帮我盯着”（MCP 的 `watch`）。

- 页面：https://socialtoai.com/zh/docs/schedules/
- 最近更新：2026-10-25

- POST: `https://api.socialtoai.com/v1/schedules`

## 谁能创建

- 任何账户都可以。没有买过积分的账户可以保留 1 个，用赠送积分运行：积分不够运行一次时自动暂停，发一封邮件告诉你，购买积分后自动恢复。再建第二个返回 HTTP 403 `plan_limit`。
- 用一把打开了“管理定期运行”权限的 Key（在控制台的 Key 设置里打开），否则返回 HTTP 403 `key_scope_denied`。也可以在控制台里做：打开一次结果，选“设为定期运行”，之后在任务页管理。
- 买过积分的账户最多 20 个。定期运行以创建它的那把 Key 的身份运行：那把 Key 撤销或到期，它就停止。

## 在 AI 应用里

在 MCP 里，同样的定期运行叫“监控”。你说“每天早上帮我盯着”，AI 应用会调两次 `watch`：`action: "preview"` 先回答会跑什么、什么时候、每次大约多少积分、每月最多多少（附约合美元），以及新内容发到哪，不扣费；你同意后，才用预览给的 `token` 调 `action: "confirm"`，按预览原样创建。`pause`、`resume`、`delete` 用它的 `id`。问“有什么新的”，`watch_news` 免费回答你的监控发现、你还没看过的新内容，最新的在前。

MCP 里成功的搜索、品牌口碑、账号监测、爆款发现结果，末尾可能带一行 `watch_hint`，问要不要每天盯着、每次大约多少积分；每小时最多一次，出错时不会出现。

## 新建一个定期运行

写明运行什么、那个请求的请求体、什么时候运行，以及一次最多花多少。创建不扣费：会先按现价报价，一次运行超过 `max_credits_per_run` 时返回 HTTP 402 `max_cost_exceeded` 和报价。

**cURL**

```
curl https://api.socialtoai.com/v1/schedules \
  -H "Authorization: Bearer $SOCIALTOAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "每日检查",
    "action": "search",
    "input": {
      "platform": "reddit",
      "query": "saturn rings"
    },
    "frequency": "daily",
    "time": "09:00",
    "timezone": "Asia/Shanghai",
    "max_credits_per_run": 4
  }'
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `tool` | string | 三选一 | 现成工具的编号：每次运行一次这个工具。 |
| `action` | string | 三选一 | 一个动作，比如 `search`：每次发一次这个调用。 |
| `op` | string | 三选一 | 平台独有接口，写成“平台.名称”，和 `POST /v1/call/{op}` 的写法一样。 |
| `input` | object | 是 | 这个调用或工具本来的请求体，包括 `platform`。不用写 `max_cost_credits` 和 `confirm`：由定期运行自己的上限代替。 |
| `name` | string \| null | 否 | 你给它起的名字，最多 80 个字符。 |
| `frequency` | "daily" \| "weekly" | 是 | 每天，或每周。 |
| `weekday` | integer | 每周时必填 | 0 是星期日，6 是星期六。 |
| `time` | string | 是 | `HH:MM`，24 小时制，按 `timezone` 计。 |
| `timezone` | string | 是 | IANA 时区，比如 `Asia/Shanghai`。时间跟着这个时区的夏令时变化走。 |
| `max_credits_per_run` | integer | 是 | 一次运行最多花多少积分。超过的那一次会被跳过，不扣费。 |
| `alert_percent` | integer | 否 | 1 到 1,000。主要数字和上一次相比变化超过这个百分比，就算一次提醒。 |
| `paused` | boolean | 仅修改时 | `true` 暂停；`false` 从下一个时点起恢复，暂停期间错过的不补跑。 |
| `email_new_items` | boolean | 否 | `true` 时，每次运行发现新内容就给你发邮件：几条新内容和前几条的链接。不设为关；从 AI 应用里建的监控默认开。 |

返回里是这个定期运行，每个路由都用同一种写法：

**201 Created** (201, 0 积分)

```
{
  "request_id": "req_00000000-0000-4000-8000-000000000020",
  "schema_version": "v1",
  "schedule": {
    "id": "00000000-0000-4000-8000-000000000021",
    "name": "每日检查",
    "tool": null,
    "action": "search",
    "op": null,
    "input": {
      "platform": "reddit",
      "query": "saturn rings"
    },
    "frequency": "daily",
    "weekday": null,
    "time": "09:00",
    "timezone": "Asia/Shanghai",
    "max_credits_per_run": 4,
    "monthly_cap_credits": 124,
    "month_spent_credits": 0,
    "alert_percent": 20,
    "status": "active",
    "stop_reason": null,
    "email_new_items": false,
    "source": "key",
    "next_run_at": "2026-10-26T01:00:00.000Z",
    "running": false,
    "last_main_number": null,
    "last_run": null,
    "created_at": "2026-10-25T08:00:00.000Z"
  },
  "quote_credits": 2
}
```

_示例：编号和时间是占位。_

## 修改、暂停、立即运行

| 方法 | 路径 | 做什么 |
| --- | --- | --- |
| POST | `/v1/schedules` | 新建。返回 201，带这个定期运行和 `quote_credits`（按现价一次运行的积分）。 |
| GET | `/v1/schedules` | 账户的全部定期运行，带 `max_schedules`（20）和 `month_runs`。 |
| GET | `/v1/schedules/{id}` | 一个定期运行。 |
| POST | `/v1/schedules/{id}` | 修改：除了运行什么，其余字段都能改。`paused: true` 暂停，`paused: false` 恢复。 |
| POST | `/v1/schedules/{id}/delete` | 删除。历次运行的扣费仍留在用量里。 |
| POST | `/v1/schedules/{id}/run` | 立即运行一次，不占它的时点，也不计入本月上限。 |
| GET | `/v1/schedules/{id}/runs` | 最近 100 个到点的时点：运行了，还是跳过了、为什么。 |

改了时间、或者暂停后恢复，都从现在之后的下一个时点继续，期间错过的不补跑。运行什么不能改，要换就新建一个。id 不存在时返回 HTTP 404 `not_found`。

## 每次花多少

- **现成工具**按所选档位的价格扣，每次都跑完整个计划。
- **动作或平台独有接口**每次读第一页，按这一页扣费，只交付新的内容：上一次已经见过的会去掉。
- 现成工具的每次运行，上一次没有的条目（按编号比）就是新内容：运行列表里的 `new_items`、邮件和 `schedule_run.finished` 都按它计。
- 每次运行在结束时按当时的价格结算。超过 `max_credits_per_run` 的那一次会被跳过。
- **每月上限**是 `max_credits_per_run` 乘以一个月最多的次数：每天的按 31 次，每周的按 5 次（`monthly_cap_credits`）。会超过它的定时运行被跳过，到下个月再继续。用 `/run` 手动发起的运行另算。
- 每个时点只运行一次。我们这边中断过的话，只补最近的那一个时点。

## 什么时候会跳过

跳过的时点不扣费。它在运行列表里的 `status` 是 `skipped`，`skip_reason` 说明原因。同一个定期运行、同一个原因，每个 UTC 日第一次跳过时会发邮件告诉你，除非你在控制台设置里关掉了运行相关的邮件。

| skip_reason | 原因 |
| --- | --- |
| `previous_run_not_finished` | 上一次运行还没结束。 |
| `key_not_usable` | 它所用的 Key 现在用不了：被暂停、撤销或到期，或者读数据、运行工具的权限被关了。 |
| `not_paid` | 账户没有买过积分，只运行它最早的那个定期运行。 |
| `plan_limit` | 免费账户不能按这个规模运行它。 |
| `unavailable` | 它要运行的接口或工具现在没有开放。 |
| `over_run_limit` | 按现行价格，一次运行超过了 `max_credits_per_run`。 |
| `monthly_cap` | 这次运行会超过本月上限。 |
| `insufficient_balance` | 余额不够这次运行。 |
| `daily_limit_reached` | Key 或账户的每日上限已到。 |
| `rate_limited` | 同时在跑的太多。 |
| 其他代码 | 请求已经不成立；值就是被拒绝时的错误代码，见[错误](https://socialtoai.com/zh/docs/api/errors.md)。 |

## 什么时候会停止

停止的定期运行不会再跑；`status` 是 `stopped`，`stop_reason` 是 `key_revoked`、`key_expired` 或 `account_closed`。Key 被撤销或到期时会发邮件告诉你。新价格会让一次运行超过上限时，在新价生效之前发邮件提醒你，可以先把上限调高。

## 提醒和结果

每次运行完成后，把主要数字和上一次比较：现成工具用它自己的主要数字，动作用这一轮的新条数。变化超过 `alert_percent`（不设时为 20），或者从 0 变成非 0，就算一次提醒：`alerted` 为 true，并向你的 [Webhook](https://socialtoai.com/zh/docs/webhooks.md) 发一条 `schedule.alert`。每次运行完成还会发 `schedule_run.finished`。

运行列表里每次运行都带 `handle`：24 小时内可以用 `GET /v1/results/{handle}` 免费读它的结果，见[结果与句柄](https://socialtoai.com/zh/docs/api/results.md)。