---
title: "Create run"
method: POST
path: "/api/v1/runs"
tags: ["Runs"]
---

# Create run

`POST /api/v1/runs`

## Request

- Base URL: `https://api.studio.kaitoi.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.studio.kaitoi.io/api/v1/runs`
- Auth: HTTP bearer

Accepts a run request for either a saved project (`projectId`) or an inline transient graph (`graph`). The server validates file input references, target nodes, node types, and input pins; snapshots the selected graph source; creates an accepted run record; and dispatches execution asynchronously through the same run lifecycle.

## Headers

- `Idempotency-Key` string, nullable
- `authorization` string, nullable

## Request body

- PublicRunCreateRequest
  - `projectId` string, nullable: Project id to snapshot and execute.
  - `graph` PublicInlineGraph
    - `nodes` PublicInlineGraphNode[], required
      - `id` string, required
      - `type` string, required
      - `title` string, nullable
      - `inputs` object
      - `position` PublicInlineGraphPosition
        - `x` union, required
          - number
          - integer
        - `y` union, required
          - number
          - integer
    - `connections` PublicInlineGraphConnection[]
      - `from` unknown, required
      - `to` unknown, required
  - `targetNodeIds` string[]: Node ids to execute. Empty means the service may choose the saved-project default target. Inline graph runs must provide at least one target node id.
  - `externalId` string, nullable
  - `externalUserId` string, nullable: Developer end-user guard. Referenced files with externalUserId must match this value.
  - `externalWorkspaceId` string, nullable
  - `inputOverrides` object: Non-persistent input overrides keyed by node id then input pin name.
  - `persistInputOverrides` boolean: Reserved for a later persistence contract. V1 run overrides default to non-persistent.

## Response `202`

Accepted run record.

- PublicRunDetail
  - `id` string, required
  - `sourceType` 'project' | 'inline_graph'
  - `projectId` string, nullable
  - `projectVersion` integer, nullable
  - `status` 'accepted' | 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
  - `cancelRequested` boolean
  - `targetNodeIds` string[]
  - `externalId` string, nullable
  - `externalUserId` string, nullable
  - `externalWorkspaceId` string, nullable
  - `inputFiles` PublicRunFileInputReference[]
    - `nodeId` string, required
    - `inputName` string, required
    - `fileId` string, required
    - `filename` string, required
    - `contentType` string, required
    - `sizeBytes` integer, required
    - `externalId` string, nullable
    - `externalUserId` string, nullable
    - `externalWorkspaceId` string, nullable
  - `outputs` object
  - `error` object, nullable
  - `creditsUsed` integer, nullable: Credits charged by this run. Null while the run is active, or when a terminal run could not produce a reliable accounting summary.
  - `creditsUsedMicrocredits` string, nullable: Exact run charge in millionths of one credit.
  - `spend` PublicRunSpendSummary
    - `totalCredits` integer, required
    - `totalMicrocredits` string, nullable
    - `byNode` PublicRunSpendNode[]
      - `nodeId` string, required
      - `nodeType` string, nullable
      - `nodeTitle` string, required
      - `credits` integer, required
      - `microcredits` string, nullable: Exact billed amount in millionths of one credit.
      - `billedRuns` integer, required: Number of cost-bearing node execution snapshots counted for this node.
    - `byProvider` object
    - `byProviderMicrocredits` object
    - `byChargeType` object
    - `byChargeTypeMicrocredits` object
  - `executionTimeMs` integer, nullable
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `400`: The run request or input references are invalid.
- `401`: Missing, malformed, expired, or revoked bearer token.
- `403`: The API key lacks the required scope or account capability.
- `404`: The project or an input file was not found.
- `409`: The Idempotency-Key conflicts with a different request.
- `422`: Validation Error
- `429`: The client or API key exceeded the REST API rate limit.
- `503`: The run could not be dispatched or the shared REST API rate limiter is temporarily unavailable.

---

[API](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api.md) · [All operations](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/revisions/239a74aa2c64?raw)