Runs

Create run

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.

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

Headers

Idempotency-Keystring nullable
authorizationstring nullable

Request body

projectIdstring nullable

Project id to snapshot and execute.

targetNodeIdsstring[]

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.

externalIdstring nullable
externalUserIdstring nullable

Developer end-user guard. Referenced files with externalUserId must match this value.

externalWorkspaceIdstring nullable
inputOverridesobject

Non-persistent input overrides keyed by node id then input pin name.

persistInputOverridesboolean

Reserved for a later persistence contract. V1 run overrides default to non-persistent.

Example request

{
  "externalUserId": "user_789",
  "inputOverrides": {
    "node_456": {
      "inputImage": {
        "fileId": "2f8f8c5df80e4f76a5b7d1bbd6fae0ab.png",
        "type": "file"
      },
      "prompt": {
        "type": "string",
        "value": "Describe this image"
      }
    }
  },
  "projectId": "project_123",
  "targetNodeIds": [
    "node_456"
  ]
}

Response

Accepted run record.

idstring required
sourceType'project' | 'inline_graph'
projectIdstring nullable
projectVersioninteger nullable
status'accepted' | 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled' required
cancelRequestedboolean
targetNodeIdsstring[]
externalIdstring nullable
externalUserIdstring nullable
externalWorkspaceIdstring nullable
outputsobject
errorobject nullable
creditsUsedinteger nullable

Credits charged by this run. Null while the run is active, or when a terminal run could not produce a reliable accounting summary.

creditsUsedMicrocreditsstring nullable

Exact run charge in millionths of one credit.

executionTimeMsinteger nullable
createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "createdAt": "2026-01-01T00:00:00Z",
  "creditsUsed": 12,
  "executionTimeMs": 2143,
  "id": "run_abc123",
  "outputs": {
    "outputImage": {
      "contentType": "image/png",
      "downloadUrl": "https://files.example/d/2f8f8c5df80e4f76a5b7d1bbd6fae0ab.png?sig=...",
      "fileId": "2f8f8c5df80e4f76a5b7d1bbd6fae0ab.png",
      "filename": "random_image.png",
      "previewUrl": "https://files.example/p/2f8f8c5df80e4f76a5b7d1bbd6fae0ab.png?sig=...",
      "sizeBytes": 482931,
      "type": "file"
    }
  },
  "sourceType": "inline_graph",
  "spend": {
    "byChargeType": {
      "provider": 12
    },
    "byNode": [
      {
        "billedRuns": 1,
        "credits": 12,
        "nodeId": "image",
        "nodeTitle": "Generate Image",
        "nodeType": "builtin/image/generate"
      }
    ],
    "byProvider": {
      "fal": 12
    },
    "totalCredits": 12
  },
  "status": "succeeded",
  "targetNodeIds": [
    "image"
  ],
  "updatedAt": "2026-01-01T00:00:03Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.