---
title: "Run an existing scheduled job immediately by id using the normal job runtime, then return the updated job state and e..."
method: POST
path: "/v1/jobs/{id}/run"
tags: ["jobs"]
---

# Run an existing scheduled job immediately by id using the normal job runtime, then return the updated job state and e...

`POST /v1/jobs/{id}/run`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/jobs/{id}/run`
- Auth: HTTP bearer

Run an existing scheduled job immediately by id using the normal job runtime, then return the updated job state and execution result for debugging. Recurring schedules belong on a package (`kody.jobs`); deferred one-shots use `workflows.create`.

Org permission: `job:execute`.

## Path parameters

- `id` string, required: Existing job id to execute immediately.

## Request body

- object

## Response `200`

Success.

- object
  - `job` object, required
    - `job_id` string, required
    - `name` string, required
    - `source_id` string, required
    - `published_commit` string, nullable, required
    - `storage_id` string, required
    - `params` object
    - `schedule` union, required
      - object
        - `type` 'once', required
        - `run_at` string, required: UTC timestamp for the one-off run, for example 2026-04-20T18:30:00Z.
      - object
        - `type` 'interval', required
        - `every` string, required: Recurring interval such as 15m, 1h, or 1d using ms, s, m, h, or d units.
      - object
        - `type` 'cron', required
        - `expression` string, required: Standard 5-field cron expression: minute hour day-of-month month day-of-week.
    - `schedule_summary` string, required
    - `timezone` string, required
    - `enabled` boolean, required
    - `kill_switch_enabled` boolean, required
    - `expires_at` string, nullable, required
    - `expired` boolean, required
    - `created_at` string, required
    - `updated_at` string, required
    - `last_run_at` string
    - `last_run_status` 'success' | 'error'
    - `last_run_error` string
    - `last_duration_ms` integer
    - `next_run_at` string, required
    - `run_count` integer, required
    - `success_count` integer, required
    - `error_count` integer, required
    - `run_history` object[], required
      - `id` string: Run record id for drill-down with runGet when available.
      - `started_at` string, required
      - `finished_at` string, required
      - `status` 'success' | 'error', required
      - `duration_ms` integer, required
      - `error` string
    - `enablement_hint` string, nullable, required: When the job is enabled but has no on enablement (or only paused ones), an agent-directed message that includes the exact enablementEnable call. Null when the job is off or already has an on enablement.
  - `execution` union, required
    - object
      - `ok` true, required
      - `result` unknown
      - `logs` string[], required
    - object
      - `ok` false, required
      - `error` string, required
      - `logs` string[], required
  - `deleted_after_run` boolean, required: Whether the job was deleted after this run. One-off jobs stay on their package instead of being deleted after running.

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/705f4f022728?raw)