### Run Development Server

Source: https://tsumugi.mq1.dev/guide/getting-started

Command to start the local development server.

```bash
pnpm wrangler dev
```

--------------------------------

### GET /api/jobs Response

Source: https://tsumugi.mq1.dev/reference/rest-api

Example JSON response for retrieving a list of jobs.

```json
{
  "jobs": [
    {
      "id": "MAIL#0:xxxxxxxxxxxxxxxxxxxxxxxx",
      "binding": "MAIL",
      "state": "FAILED",
      "priority": 0,
      "attempts": 3,
      "max_attempts": 3,
      "created_at": 1753000000000,
      "updated_at": 1753000060000,
      "dispatched_at": 1753000030000,
      "retryable": true
    }
  ],
  "total": 1
}
```

--------------------------------

### Start a Flow Execution

Source: https://tsumugi.mq1.dev/guide/flow

Initiate a flow execution using the start method. You can provide an optional ID to fix the runId or set a deadline for the entire run.

```typescript
const runId = await tsumugi.start(env, 'GREETINGS', { prefix: 'hello' });
```

--------------------------------

### Install Tsumugi

Source: https://tsumugi.mq1.dev/guide/getting-started

Commands to create a new Cloudflare project and add the Tsumugi package.

```bash
pnpm create cloudflare@latest my-jobs --type=hello-world
cd my-jobs
pnpm add tsumugi
```

--------------------------------

### GET /api/bindings

Source: https://tsumugi.mq1.dev/reference/rest-api

投入先の選択肢と絞り込み用のbinding名を返します。一度も実行されていないbindingも含めて、`performers`に登録された全てのbindingを返します。

```APIDOC
## GET /api/bindings

### Description
投入先の選択肢と絞り込み用のbinding名を返します。一度も実行されていないbindingも含めて、`performers`に登録された全てのbindingを返します。

### Method
GET

### Endpoint
/api/bindings

### Response
#### Success Response (200)
- **bindings** (array) - binding名の一覧

#### Response Example
```json
{ "bindings": ["CHARGE", "MAIL"] }
```
```

--------------------------------

### GET /api/diagnostics Response Body

Source: https://tsumugi.mq1.dev/reference/rest-api

Example response showing execution status, blocking reasons, and current policies for each binding on shard 0.

```json
{
  "shard": 0,
  "bindings": {
    "MAIL": {
      "active": 2,
      "outbox": 0,
      "blocked": { "paused": false, "capacity": true, "tokens": false, "perKey": false, "perKeyTokens": false },
      "policy": {
        "paused": false,
        "concurrency": 100,
        "perKeyConcurrency": 1,
        "rate": null,
        "perKeyRate": null,
        "agingIntervalMs": 60000,
        "reaperGraceMs": 30000
      }
    }
  }
}
```

--------------------------------

### GET /api/diagnostics

Source: https://tsumugi.mq1.dev/reference/rest-api

bindingごとに、実行待ちのジョブが待機している原因を取得するエンドポイントです。

```APIDOC
## GET /api/diagnostics

### Description
bindingごとに、実行待ちのジョブが待機している原因を取得します。

### Method
GET

### Endpoint
/api/diagnostics

### Response
#### Success Response (200)
- **shard** (number) - シャード番号
- **bindings** (object) - bindingごとの診断情報
  - **active** (number) - 実行中の件数
  - **outbox** (number) - 一覧への反映を待っている件数
  - **blocked** (object) - 実行待ちのジョブがどの制約で待機しているかの内訳
    - **paused** (boolean) - 一時停止
    - **capacity** (boolean) - 同時実行数
    - **tokens** (boolean) - レート
    - **perKey** (boolean) - キー単位の同時実行数
    - **perKeyTokens** (boolean) - キー単位のレート
  - **policy** (object) - 現在適用されている実行量の設定
    - **paused** (boolean) - 一時停止
    - **concurrency** (number) - 同時実行数
    - **perKeyConcurrency** (number) - キー単位の同時実行数
    - **rate** (number|null) - レート
    - **perKeyRate** (number|null) - キー単位のレート
    - **agingIntervalMs** (number) - エージング間隔
    - **reaperGraceMs** (number) - リーパーの猶予時間

#### Response Example
```json
{
  "shard": 0,
  "bindings": {
    "MAIL": {
      "active": 2,
      "outbox": 0,
      "blocked": { "paused": false, "capacity": true, "tokens": false, "perKey": false, "perKeyTokens": false },
      "policy": {
        "paused": false,
        "concurrency": 100,
        "perKeyConcurrency": 1,
        "rate": null,
        "perKeyRate": null,
        "agingIntervalMs": 60000,
        "reaperGraceMs": 30000
      }
    }
  }
}
```

### Notes
- 対象はshard 0のみです。分割している場合、他のshardは含まれません。
```

--------------------------------

### GET /api/runs

Source: https://tsumugi.mq1.dev/reference/rest-api

Runの一覧を返します。クエリパラメータで状態やFlow名による絞り込み、ページングが可能です。

```APIDOC
## GET /api/runs

### Description
Runの一覧を返します。

### Method
GET

### Endpoint
/api/runs

### Parameters
#### Query Parameters
- **state** (string) - Optional - `RUNNING` `COMPLETED` `FAILED` `CANCELLED`
- **flow** (string) - Optional - Flow名による絞り込み
- **limit** (integer) - Optional - 最大100 (既定: 20)
- **offset** (integer) - Optional - ページング (既定: 0)

### Response
#### Success Response (200)
- **runs** (array of object) - Runの一覧
  - **id** (string) - Run ID
  - **flow** (string) - Flow名
  - **state** (string) - 状態
  - **node_total** (integer) - ノード総数
  - **node_done** (integer) - 完了ノード数
  - **node_failed** (integer) - 失敗ノード数
  - **created_at** (integer) - 作成時刻 (エポックミリ秒)
  - **updated_at** (integer) - 更新時刻 (エポックミリ秒)
- **total** (integer) - 総数

#### Response Example
```json
{
  "runs": [
    {
      "id": "GREETINGS:cl9x0a1b2c3d",
      "flow": "GREETINGS",
      "state": "RUNNING",
      "node_total": 6,
      "node_done": 4,
      "node_failed": 0,
      "created_at": 1767225600000,
      "updated_at": 1767225603000
    }
  ],
  "total": 1
}
```
```

--------------------------------

### Configure Shards for Binding

Source: https://tsumugi.mq1.dev/guide/execution

Example of setting the number of shards for a specific binding. When shards are 2 or more, a partitionKey is required.

```typescript
bindings: {
  MAIL: { shards: 4 },
}
```

--------------------------------

### GET /api/metrics

Source: https://tsumugi.mq1.dev/reference/rest-api

binding別の失敗率と所要時間を返すエンドポイントです。

```APIDOC
## GET /api/metrics

### Description
Analytics Engineに書いた時系列から、binding別の失敗率と所要時間を返します。

### Method
GET

### Endpoint
/api/metrics

### Parameters
#### Query Parameters
- **hours** (number) - Optional - 遡る時間。1以上720以下。既定値は`24`。
- **binding** (string) - Optional - binding名での絞り込み。既定値はなし。

### Response
#### Success Response (200)
- **hours** (number) - 遡った時間
- **bindings** (array) - binding別の集計結果
  - **binding** (string) - binding名
  - **total** (number) - 総件数
  - **failed** (number) - 失敗件数
  - **failureRate** (number) - 失敗率
  - **avgDurationMs** (number) - 平均所要時間
  - **maxDurationMs** (number) - 最大所要時間
  - **p95DurationMs** (number) - 95パーセンタイル所要時間
  - **avgAttempts** (number) - 平均試行回数
- **series** (array) - 時系列データ
  - **at** (number) - タイムスタンプ
  - **total** (number) - 総件数
  - **failed** (number) - 失敗件数
  - **avgDurationMs** (number) - 平均所要時間

#### Response Example
```json
{
  "hours": 24,
  "bindings": [
    {
      "binding": "MAIL",
      "total": 1200,
      "failed": 18,
      "failureRate": 0.015,
      "avgDurationMs": 820,
      "maxDurationMs": 5400,
      "p95DurationMs": 2100,
      "avgAttempts": 1.04
    }
  ],
  "series": [{ "at": 1753000000000, "total": 50, "failed": 1, "avgDurationMs": 810 }]
}
```

### Error Handling
- `hours`が範囲外、または`binding`が不正な名前の場合は400になります。
- `metrics`を設定していない構成では501を返します。
- Analytics Engineが要求を拒否した場合と応答が無い場合は502を返し、本文に理由が含まれます。
```

--------------------------------

### GET /api/openapi.json

Source: https://tsumugi.mq1.dev/reference/rest-api

OpenAPI 3.1の定義を返します。全エンドポイントのパラメータと応答の形を記述したものです。

```APIDOC
## GET /api/openapi.json

### Description
OpenAPI 3.1の定義を返します。全エンドポイントのパラメータと応答の形を記述したものです。

### Method
GET

### Endpoint
/api/openapi.json

### Response
#### Success Response (200)
- OpenAPI 3.1定義 (JSON)
```

--------------------------------

### POST /api/bindings/:binding/policy Request Body

Source: https://tsumugi.mq1.dev/reference/rest-api

Example request body to update runtime execution settings for a binding.

```json
{ "paused": true, "concurrency": 5 }
```

--------------------------------

### Simulate a flow with simulateFlow and assert node order and payloads

Source: https://tsumugi.mq1.dev/guide/flow

Imports simulateFlow from 'tsumugi/testing' and runs it with a results map keyed by node ID. It does not execute performers; unspecified node return values are undefined. The example asserts the execution order and the payload passed to the second node.

```TypeScript
import { simulateFlow } from 'tsumugi/testing';

const result = simulateFlow(flows.GREETINGS, { prefix: 'hello' }, { results: { list: { names: ['a', 'b'] } } });

expect(result.nodes.map((node) => node.id)).toEqual(['list', 'greet:0', 'greet:1', 'greet', 'report']);
expect(result.nodes[1].payload).toEqual({ name: 'a' });
```

--------------------------------

### Wrangler service binding configuration

Source: https://tsumugi.mq1.dev/reference/config

Example configuration for a service binding in wrangler.toml or equivalent JSONC configuration, used when a performer requires remote service access.

```jsonc
"services": [
  { "binding": "MAIL", "service": "my-mailer", "entrypoint": "SendMail" },
]
```

--------------------------------

### Define and Enqueue a Job

Source: https://tsumugi.mq1.dev/guide/overview

Define a job by exporting a Performer class and enqueue it using the enqueue function. The example demonstrates the basic structure for creating and triggering a job.

```ts
import { enqueue } from 'tsumugi';
import { Performer } from 'tsumugi/performer';

// 1. ジョブの中身をperformerとして定義してexportする
export class SendMail extends Performer<{ to: string }, void, {}, Env> {
  async perform(payload: { to: string }): Promise<void> {
    await this.env.MAILER.send(payload.to);
  }
}

// 2. 投入する。binding名はexportした名前
const id = await enqueue(env, { binding: 'SendMail', payload: { to: 'a@example.com' } });
```

--------------------------------

### Run tsumugi CLI in interactive mode

Source: https://tsumugi.mq1.dev/reference/cli

Starts the interactive mode of the tsumugi CLI. In non-TTY environments (e.g., pipes or CI), it does not enter interactive mode and exits with usage information.

```bash
npx tsumugi
```

--------------------------------

### Initialize Tsumugi

Source: https://tsumugi.mq1.dev/guide/getting-started

Run the initialization command to create resources and generate the project structure.

```bash
npx tsumugi init
```

--------------------------------

### GET /api/metrics Response Body

Source: https://tsumugi.mq1.dev/reference/rest-api

Example response containing failure rates and duration metrics for bindings, aggregated from the Analytics Engine.

```json
{
  "hours": 24,
  "bindings": [
    {
      "binding": "MAIL",
      "total": 1200,
      "failed": 18,
      "failureRate": 0.015,
      "avgDurationMs": 820,
      "maxDurationMs": 5400,
      "p95DurationMs": 2100,
      "avgAttempts": 1.04
    }
  ],
  "series": [{ "at": 1753000000000, "total": 50, "failed": 1, "avgDurationMs": 810 }]
}
```

--------------------------------

### GET /api/stats Response Body

Source: https://tsumugi.mq1.dev/reference/rest-api

Example response showing the count of jobs by state and the wait time of the oldest scheduled job.

```json
{
  "byState": { "SCHEDULED": 12, "RUNNING": 3, "COMPLETED": 480, "FAILED": 2 },
  "oldestScheduledMs": 45000
}
```

--------------------------------

### Initialize Tsumugi project with tsumugi init

Source: https://tsumugi.mq1.dev/reference/cli

Sets up Tsumugi in a project. Options: --name to specify the Worker name, --format to choose jsonc or toml (default jsonc). Creates resources, generates config and source files, and runs migrations and types.

```bash
npx tsumugi init [--name <name>] [--format jsonc|toml]
```

--------------------------------

### tsumugi.jobs(env) で型付き投入オブジェクトを作成する

Source: https://tsumugi.mq1.dev/guide/enqueue

`tsumugi.jobs(env)` は env を渡して作る型付きの投入用オブジェクト。`jobs.enqueue` の引数の形が `tsumugi.enqueue` と異なる。キーを必須にした performer では、`options` の省略とキーの渡し忘れがコンパイルエラーになる。

```ts
const jobs = tsumugi.jobs(env);

const id = await jobs.enqueue('MAIL', { to: 'a@example.com', subject: 'hi' });
await jobs.enqueue('CHARGE', { customerId: 'c1', amountJpy: 1200 }, { concurrencyKey: 'customer:c1' });
```

--------------------------------

### GET /api/jobs/:id Response

Source: https://tsumugi.mq1.dev/reference/rest-api

Example JSON response for retrieving detailed information about a specific job, including trial history.

```json
{
  "job": {
    "id": "MAIL#0:xxxxxxxxxxxxxxxxxxxxxxxx",
    "binding": "MAIL",
    "state": "FAILED",
    "payload": "{\"to\":\"a@example.com\"}",
    "result": null,
    "priority": 0,
    "attempts": 3,
    "max_attempts": 3,
    "progress": null,
    "concurrency_key": "domain:example.com",
    "unique_key": null,
    "guarantee": "at-least-once",
    "created_at": 1753000000000,
    "updated_at": 1753000060000,
    "dispatched_at": 1753000030000,
    "run_after": null,
    "retryable": true,
    "attempts_log": [
      {
        "attempt": 1,
        "state": "FAILED",
        "started_at": 1753000010000,
        "finished_at": 1753000012000,
        "error": "payment failed: 502"
      }
    ]
  }
}
```

--------------------------------

### Enqueue Job with at-most-once Guarantee

Source: https://tsumugi.mq1.dev/guide/execution

Example of enqueuing a job with the 'at-most-once' guarantee, which prevents duplicate execution but increases start latency.

```typescript
await tsumugi.enqueue(env, {
  binding: 'CHARGE',
  payload,
  guarantee: 'at-most-once',
});
```

--------------------------------

### Add a Performer

Source: https://tsumugi.mq1.dev/guide/getting-started

Command to add a new performer to the project.

```bash
npx tsumugi add-performer send-mail
```

--------------------------------

### 実行時の上書き（configure）

Source: https://tsumugi.mq1.dev/guide/execution

コードからstubのconfigureを使用してポリシーを変更する例。

```ts
await tsumugi.shardFor(env, 'MAIL').configure({ policy: { concurrency: 5 } });
```

--------------------------------

### GET /api/runs/:id

Source: https://tsumugi.mq1.dev/reference/rest-api

1つのRunとそのノードを並び順で返します。ノードの詳細情報（状態、親子関係、結果など）が含まれます。

```APIDOC
## GET /api/runs/:id

### Description
1つのRunと、そのノードを並び順で返します。

### Method
GET

### Endpoint
/api/runs/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - Run ID

### Response
#### Success Response (200)
- **run** (object) - Runの詳細
  - **id** (string) - Run ID
  - **flow** (string) - Flow名
  - **state** (string) - 状態
  - **input** (string) - 入力JSON (文字列)
  - **node_total** (integer) - ノード総数
  - **node_done** (integer) - 完了ノード数
  - **node_failed** (integer) - 失敗ノード数
  - **created_at** (integer) - 作成時刻
  - **updated_at** (integer) - 更新時刻
  - **parent_run_id** (string|null) - 親Run ID
  - **parent_node_id** (string|null) - 親ノード ID
  - **retryable** (boolean) - 再試行可能か
- **nodes** (array of object) - ノードの一覧
  - **id** (string) - ノード ID
  - **binding** (string) - バインディング
  - **state** (string) - 状態
  - **container** (boolean) - fan-outノードかどうか
  - **parent** (string|null) - 親ノード ID
  - **origin** (string) - 生成元 (`static`, `fanOut`, `spawn`)
  - **after** (array of string) - 依存ノード
  - **job_id** (string|null) - ジョブ ID
  - **child_run_id** (string|null) - 子Run ID
  - **result** (any|null) - 結果
  - **error** (any|null) - エラー
  - **position** (integer) - 位置
  - **created_at** (integer) - 作成時刻
  - **updated_at** (integer) - 更新時刻

#### Response Example
```json
{
  "run": {
    "id": "GREETINGS:cl9x0a1b2c3d",
    "flow": "GREETINGS",
    "state": "RUNNING",
    "input": "{\"prefix\":\"hello\"}",
    "node_total": 6,
    "node_done": 4,
    "node_failed": 0,
    "created_at": 1767225600000,
    "updated_at": 1767225603000,
    "parent_run_id": null,
    "parent_node_id": null,
    "retryable": false
  },
  "nodes": [
    {
      "id": "greet",
      "binding": "GREET",
      "state": "RUNNING",
      "container": true,
      "parent": null,
      "origin": "static",
      "after": ["list"],
      "job_id": null,
      "child_run_id": null,
      "result": null,
      "error": null,
      "position": 1,
      "created_at": 1767225600000,
      "updated_at": 1767225603000
    }
  ]
}
```
```

--------------------------------

### createClient でジョブを投入する

Source: https://tsumugi.mq1.dev/guide/client

`tsumugi/client`から`createClient`をインポートし、`enqueue`メソッドでジョブを1件投入します。Durable Objectの実装を参照しないため、投入側のWorkerのバンドルには含まれません。

```ts
import { createClient } from 'tsumugi/client';

const jobs = createClient<Env>();

export default {
  async fetch(request, env) {
    const id = await jobs.enqueue(env, {
      binding: 'MAIL',
      payload: { to: 'a@example.com', subject: 'hi' },
    });
    return Response.json({ id });
  },
} satisfies ExportedHandler<Env>;
```

--------------------------------

### Apply Migrations

Source: https://tsumugi.mq1.dev/guide/getting-started

Command to apply migrations after updating Tsumugi.

```bash
pnpm wrangler d1 migrations apply my-jobs --local
pnpm wrangler d1 migrations apply my-jobs --remote
```

--------------------------------

### GET /api/schedules

Source: https://tsumugi.mq1.dev/reference/rest-api

定期実行の一覧を取得します。ジョブの一覧と異なり、反映の遅れはありません。

```APIDOC
## GET /api/schedules

### Description
定期実行の一覧を取得します。ジョブの一覧と異なり、反映の遅れはありません。

### Method
GET

### Endpoint
/api/schedules

### Response
#### Success Response (200)
- **schedules** (array) - スケジュールの一覧
  - **name** (string) - スケジュールの名前。`schedules`のキー
  - **kind** (string) - `job`または`flow`
  - **target** (string) - binding名またはFlow名
  - **every_ms** (integer) - 固定間隔。`cron`を指定した場合は`null`
  - **cron** (string) - cron式。`everyMs`を指定した場合は`null`
  - **time_zone** (string) - cronと表示に使うIANAタイムゾーン。固定間隔では`UTC`
  - **overlap** (string) - `skip`または`overlap`
  - **next_run_at** (integer) - 次回の実行予定
  - **last_run_at** (integer) - 直近の発火の予定時刻。一度も発火していない場合は`null`
  - **last_fired_at** (integer) - 直近の発火の実時刻。`last_run_at`との差が遅れ
  - **last_job_id** (string) - 直近の発火で投入したジョブ。`kind`が`flow`の場合は`null`
  - **last_run_id** (string) - 直近の発火で開始したRun。`kind`が`job`の場合は`null`
  - **last_skipped_at** (integer) - 直近で発火しなかった時刻。一度も該当がない場合は`null`
  - **skipped_count** (integer) - 前回が終わっていないために発火しなかった回数
  - **last_error** (string) - 直近の発火が失敗した理由。成功した場合は`null`

#### Response Example
```json
{
  "schedules": [
    {
      "name": "nightly",
      "kind": "flow",
      "target": "REPORT",
      "every_ms": null,
      "cron": "0 3 * * *",
      "time_zone": "Asia/Tokyo",
      "overlap": "skip",
      "next_run_at": 1767722400000,
      "last_run_at": 1767636000000,
      "last_fired_at": 1767636001200,
      "last_job_id": null,
      "last_run_id": "REPORT:nightly-1767636000000",
      "last_skipped_at": null,
      "skipped_count": 0,
      "last_error": null
    }
  ]
}
```

#### Error Response (501)
- **error** (string) - エラーメッセージ
```

--------------------------------

### Apply D1 Migrations

Source: https://tsumugi.mq1.dev/guide/flow

Run this command to apply D1 migrations after updating your configuration.

```bash
pnpm wrangler d1 migrations apply my-jobs --remote
```

--------------------------------

### Add a performer with tsumugi add-performer

Source: https://tsumugi.mq1.dev/reference/cli

Adds a performer by generating a class file and updating the barrel file. The name can be in kebab-case, camelCase, PascalCase, or SNAKE_CASE; it is converted to PascalCase for the class name and kebab-case for the filename. If a file or export already exists, it exits without writing.

```bash
npx tsumugi add-performer <NAME>
```

--------------------------------

### GET /api/stats

Source: https://tsumugi.mq1.dev/reference/rest-api

状態別の件数を返すエンドポイントです。

```APIDOC
## GET /api/stats

### Description
状態別の件数を返します。

### Method
GET

### Endpoint
/api/stats

### Response
#### Success Response (200)
- **byState** (object) - 状態別の件数
- **oldestScheduledMs** (number|null) - 最も古い`SCHEDULED`のジョブが投入から待機している時間。対象が無い場合はnull。

#### Response Example
```json
{
  "byState": { "SCHEDULED": 12, "RUNNING": 3, "COMPLETED": 480, "FAILED": 2 },
  "oldestScheduledMs": 45000
}
```
```

--------------------------------

### GET /api/flows

Source: https://tsumugi.mq1.dev/reference/rest-api

登録済みのFlow名を取得します。一度も実行されていないFlowも含めて、`flows`に登録された全てのFlow名を取得できます。

```APIDOC
## GET /api/flows

### Description
登録済みのFlow名を取得します。

### Method
GET

### Endpoint
/api/flows

### Response
#### Success Response (200)
- **flows** (array of string) - 登録済みのFlow名の一覧

#### Response Example
```json
{ "flows": ["GREETINGS", "PIPELINE"] }
```
```

--------------------------------

### ui()でダッシュボードを有効にする

Source: https://tsumugi.mq1.dev/guide/dashboard

tsumugi/uiのui()をdefineTsumugiに渡すとダッシュボードが有効になります。tokenCookieオプションはトークンを保存するcookie名で、bearerAuthのcookieと揃えます。サブパスに分割しているため、指定しない場合はバンドルに含まれません。

```ts
import { ui } from 'tsumugi/ui';

const tsumugi = defineTsumugi({
  performers,
  auth: bearerAuth((env: Env) => env.TSUMUGI_TOKEN, { cookie: 'tsumugi_token' }),
  ui: ui({ tokenCookie: 'tsumugi_token' }),
});
```

--------------------------------

### 直列化: concurrencyKey を指定する

Source: https://tsumugi.mq1.dev/guide/enqueue

`concurrencyKey` が同じジョブは、`perKeyConcurrency` の上限まで同時に実行される。既定は1であり、同じキーのジョブは1件ずつ順に実行される。この保証が成立するのは shard 数が1の場合のみ。

```ts
await tsumugi.enqueue(env, {
  binding: 'CHARGE',
  payload: { customerId: 'c1', amountJpy: 1200 },
  concurrencyKey: 'customer:c1',
});
```

--------------------------------

### Define a Performer

Source: https://tsumugi.mq1.dev/guide/getting-started

Example of a minimal performer class in src/performers/hello.ts.

```typescript
// src/performers/hello.ts
import { Performer } from 'tsumugi/performer';

export class Hello extends Performer<{ name: string }, void, {}, Env> {
  async perform(payload: { name: string }): Promise<void> {
    console.log(`hello, ${payload.name}`);
  }
}
```

--------------------------------

### POST /api/bindings/:binding/policy

Source: https://tsumugi.mq1.dev/reference/rest-api

実行量の設定を実行時に変更します。明示した項目のみが変更され、省略した項目は変更されません。変更はbindingのすべてのshardへ適用されます。

```APIDOC
## POST /api/bindings/:binding/policy

### Description
実行量の設定を実行時に変更します。明示した項目のみが変更され、省略した項目は変更されません。変更はbindingのすべてのshardへ適用されます。

### Method
POST

### Endpoint
/api/bindings/:binding/policy

### Parameters
#### Path Parameters
- **binding** (string) - Required - binding名

#### Request Body
- **paused** (boolean) - Optional - 投入の一時停止。実行中のジョブの監視は継続します
- **concurrency** (integer) - Optional - 同時実行数。0以上の整数
- **perKeyConcurrency** (integer) - Optional - キー単位の同時実行数。0以上の整数
- **rate** (object) - Optional - `{ tokens, intervalMs }`。`null`でレート制限を解除します
- **perKeyRate** (object) - Optional - `{ tokens, intervalMs }`。キー単位のレート制限。`null`で解除します
- **agingIntervalMs** (integer) - Optional - エージングの間隔。`null`で無効
- **reaperGraceMs** (integer) - Optional - 無応答と判定するまでの猶予。0以上の整数

### Request Example
```json
{ "paused": true, "concurrency": 5 }
```

### Response
#### Success Response (200)
- **binding** (string) - binding名
- **shards** (integer) - 適用されたshard数
- **policy** (object) - 変更後の設定

#### Response Example
```json
{
  "binding": "MAIL",
  "shards": 1,
  "policy": {
    "paused": true,
    "concurrency": 5,
    "perKeyConcurrency": 1,
    "rate": null,
    "perKeyRate": null,
    "agingIntervalMs": 60000,
    "reaperGraceMs": 30000
  }
}
```

#### Error Response (500)
- **error** (string) - エラーメッセージ
- **binding** (string) - binding名
- **shards** (integer) - 総shard数
- **failed** (array) - 適用されなかったshardの番号

#### Error Response Example
```json
{ "error": "the change reached 3 of 4 shards, send the same request again", "binding": "MAIL", "shards": 4, "failed": [2] }
```
```

--------------------------------

### GET /api/runs/:id

Source: https://tsumugi.mq1.dev/reference/rest-api

Retrieves details for a specific run and its nodes in execution order.

```json
{
  "run": {
    "id": "GREETINGS:cl9x0a1b2c3d",
    "flow": "GREETINGS",
    "state": "RUNNING",
    "input": "{\"prefix\":\"hello\"}",
    "node_total": 6,
    "node_done": 4,
    "node_failed": 0,
    "created_at": 1767225600000,
    "updated_at": 1767225603000,
    "parent_run_id": null,
    "parent_node_id": null,
    "retryable": false
  },
  "nodes": [
    {
      "id": "greet",
      "binding": "GREET",
      "state": "RUNNING",
      "container": true,
      "parent": null,
      "origin": "static",
      "after": ["list"],
      "job_id": null,
      "child_run_id": null,
      "result": null,
      "error": null,
      "position": 1,
      "created_at": 1767225600000,
      "updated_at": 1767225603000
    }
  ]
}
```

--------------------------------

### 予約実行: delayMs と runAt を使用する

Source: https://tsumugi.mq1.dev/guide/enqueue

`delayMs` で実行開始を遅らせ、`runAt` で絶対時刻を指定して予約実行する。12時間より先の予約も指定可能。

```ts
// 1時間後
await tsumugi.enqueue(env, { binding: 'MAIL', payload, delayMs: 60 * 60 * 1000 });

// 指定時刻
await tsumugi.enqueue(env, { binding: 'MAIL', payload, runAt: Date.parse('2026-08-01T09:00:00+09:00') });
```