---
title: "Create a durable function run"
method: POST
path: "/functions/v1/{name}/runs"
tags: ["Functions"]
---

# Create a durable function run

`POST /functions/v1/{name}/runs`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/functions/v1/{name}/runs`
- Auth: HTTP bearer

Create an idempotent delayed/reliable request for a deployed function. When due, the function receives X-Run402-Trigger: function_run and a typed JSON envelope. Temporary concurrency occupancy waits automatically without consuming execution attempts; lifecycle and exhausted-quota gates remain blocked.

## Path parameters

- `name` string, required

## Headers

- `Idempotency-Key` string
- `X-Run402-Parent-Run-Id` string
- `X-Run402-Parent-Attempt-Id` string

## Request body

- FunctionRunCreateRequest
  - `event_type` string, required
  - `payload` object
  - `idempotency_key` string: Stable idempotency key. May be mirrored by the Idempotency-Key header.
  - `run_at` string, date-time: Absolute execution time. Mutually exclusive with delay_seconds.
  - `delay_seconds` number: Relative execution delay in seconds. Mutually exclusive with run_at.
  - `expires_at` string, date-time: Optional deadline after which an unstarted run expires.
  - `retry` object
    - `preset` string
    - `max_attempts` integer
    - `min_delay_seconds` integer
    - `max_delay_seconds` integer

## Response `200`

Function run

- FunctionRunHandle
  - `run_id` string, required
  - `function_name` string, required
  - `event_type` string, required
  - `status` 'scheduled' | 'queued' | 'running' | 'retrying' | 'blocked' | 'succeeded' | 'failed' | 'cancelled' | 'expired', required
  - `terminal` boolean, required
  - `generation` integer, required
  - `run_at` string, date-time, required
  - `expires_at` string, date-time
  - `source` object, required
  - `attempts` object, required
    - `current` integer, required
    - `max` integer, required
    - `total` integer, required
    - `next_attempt_at` string, date-time
  - `last_attempt` object
    - `attempt_id` string
    - `number` integer
    - `started_at` string, date-time
    - `completed_at` string, date-time
    - `duration_ms` integer
    - `response_status` integer
    - `error` FunctionRunErrorInfo
      - `code` string, required
      - `message` string, required
      - `retryable` boolean, required
  - `last_error` FunctionRunErrorInfo
    - `code` string, required
    - `message` string, required
    - `retryable` boolean, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `completed_at` string, date-time
  - `deduplicated` boolean
  - `next_actions` object[], required

## Other responses

- `202`: Function run
- `400`: Run402-originated JSON bodies use the canonical ErrorEnvelope.
- `401`: Missing or invalid authentication. Run402-originated JSON bodies use the canonical ErrorEnvelope.
- `409`: Run402-originated JSON bodies use the canonical ErrorEnvelope.

---

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