---
title: "Create Agent Run"
method: POST
path: "/api/v1/agents/{agent_id}/runs"
tags: ["agents"]
---

# Create Agent Run

`POST /api/v1/agents/{agent_id}/runs`

## Path parameters

- `agent_id` string, required

## Headers

- `x-api-key` string, required

## Request body

- CreateRunRequest
  - `input_params` object, required
  - `user_api_key` string, nullable

## Response `200`

Successful Response

- AgentRunResponse
  - `id` string, required
  - `agent_id` string, required
  - `workspace_id` string, required
  - `status` 'pending' | 'running' | 'completed' | 'failed', required
  - `input_params` object, required
  - `output` unknown
  - `tracked_task_ids` string[], required
  - `container_id` string, nullable
  - `container_port` integer, nullable
  - `container_host` string, nullable
  - `node_logs` NodeLog[]
    - `node_id` string, required
    - `node_name` string, required
    - `status` string, required
    - `started_at` string, date-time, nullable
    - `completed_at` string, date-time, nullable
    - `output` unknown
    - `error` string, nullable
  - `error` string, nullable
  - `suggested_fix` string, nullable
  - `retry_count` integer
  - `started_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `created_by` string, required
  - `created_at` string, date-time, required
  - `trigger_source` string, nullable
  - `trigger_source_id` string, nullable
  - `agent_dag_json` AgentDagSchema
    - `nodes` AgentNodeSchema[]
      - `id` string, required
      - `name` string, required
      - `description` string
      - `type` string, required
      - `automation_ids` string[]
      - `qa_answers` object
      - `branches` BranchArmSchema[]
        - `id` string, required
        - `condition` string
        - `nodes` BranchArmNodeSchema[]
          - `id` string, required
          - `name` string, required
          - `description` string
          - `type` string
          - `automation_ids` string[]
    - `edges` AgentEdgeSchema[]
      - `source` string, required
      - `target` string, required
  - `agent_plan_summary` string, nullable
  - `agent_name` string, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-11** `fd7237c72fae` — 2 info
  - added the optional property `trigger_source` to the response with the `200` status
  - added the optional property `trigger_source_id` to the response with the `200` status
- **2026-07-26** `653b9ca575a8` — 1 breaking, 2 info
  - the response property `node_logs` became optional for the status `200`
  - added the optional property `agent_name` to the response with the `200` status
  - the `node_logs` response's property default value `` was added for the status `200`

[Change history](https://skmtc.dev/optexity/apis/dashboard-backend-api/changes/api/v1/agents/:agent_id/runs/post.md)

---

[API](https://skmtc.dev/optexity/apis/dashboard-backend-api.md) · [All operations](https://skmtc.dev/optexity/apis/dashboard-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/optexity/dashboard-backend-api/revisions/2e974096944a/schema)