---
title: "Run a product [write]"
method: POST
path: "/runs"
---

# Run a product \[write\]

`POST /runs`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/runs`
- Auth: HTTP bearer

String input is a shortcut. Agent objects preserve one user message and optional system message. Direct Agent Runs prepare a Session with platform billing; an existing Session retains its payer and billing settings. Non-streaming waits up to ten seconds. SSE begins with the durable Run identity. Disconnect never cancels execution. A catalog handle (`@handle`) runs that agent as one turn of a new session of it, charged as that session is: `addons` may set `model`, within the agent's engine, and `instructions`, files added after the agent's own, and nothing else; a `user.message` sent to the Run (POST /runs/{id}/events) is the next turn of that session and a Run of its own. When a Run of a handle ends, each webhook endpoint of the workspace subscribed to `run.completed`, `run.interrupted`, `run.failed` or `run.blocked` receives that event once, signed like every other webhook. A handle whose agent has not passed its checks is refused with `listing_not_checked` or `listing_checks_failed`.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `product` string, required
  - `input` unknown, required
  - `addons` object
  - `session_id` string
  - `stream` boolean
  - `metadata` object

## Response `200`

Durable Run identity, status, output and references to authoritative billing.

- object
  - `run` object
    - `id` string, required
    - `product` string, nullable, required
    - `session_id` string, nullable, required
    - `status` 'queued' | 'running' | 'waiting_input' | 'stopping' | 'completed' | 'interrupted' | 'failed' | 'blocked' | 'reconciling', required
    - `output` unknown, required
    - `output_available` boolean
    - `usage` unknown, required
    - `billing` unknown, required
    - `error` unknown, required
    - `artifact` object
      - `id` string, required
      - `mediaType` string, required
      - `url` string, uri, required
    - `source` object
      - `goal_id` string
      - `iteration` integer
      - `routine_run_id` string
      - `routine_id` string
    - `created_at` string, required
    - `completed_at` string, nullable, required

## Other responses

- `202`: Durable Run identity, status, output and references to authoritative billing.
- `409`: Session busy or conflicting idempotency key
- `422`: The product cannot be run: a listed agent that has not passed its checks, or an override that is not allowed
- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/runs/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)