Start automated task running¶

Manually start an enabled scheduled automation task and create a run record.

HTTP
POST $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/agent-automation-tasks/{automation_task_id}/runs

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First Query automation task detailsConfirm that the task is enabled and obtain the task ID.

Set the operation-specific values used in the request:

$WORKSPACE_ID: Target workspace ID, passed through the X-Workspace-ID header and also as workspace_id in the path.
$TASK_ID: The automation task ID to start, as automation_task_id in the path.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/agent-automation-tasks/$TASK_ID/runs" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "payload": {
      "date": "2026-08-18"
    }
  }'

Parameter reference

Path parameters

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Workspace ID.
`automation_task_id`	string	Yes	Automation task ID.

Request body

Parameters	Type	Is it required	Description
`payload`	object	No	Input data for this run.
`trigger_context`	object	No	Additional context for this trigger.

Successful response¶

Returns 201 on success. The fact that the request has been submitted does not mean that the agent has completed execution; please continue to query the running details or results.

Response example

JSON
{
  "code": 0,
  "data": {
    "id": "run_01",
    "workspace_id": "ws_01",
    "automation_task_id": "task_01",
    "automation_task_version": 1,
    "trigger_type": "manual",
    "trigger_config_snapshot": {
      "mode": "cron"
    },
    "status": "queued",
    "created_at": "2026-08-18T04:00:00Z",
    "updated_at": "2026-08-18T04:00:00Z"
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.id`	string	New run, workspace, and automation task identifiers.
`data.workspace_id`	string	New run, workspace, and automation task identifiers.
`data.automation_task_id`	string	New run, workspace, and automation task identifiers.
`data.automation_task_version`	integer	The task version used in this run.
`data.trigger_type`	string	Trigger type and configuration snapshot fixed to manual triggering.
`data.trigger_config_snapshot`	object	Trigger type and configuration snapshot fixed to manual triggering.
`data.status`	string	Initial running status; please refer to the subsequent query status.
`data.created_at`	string	Creation and last update times, using RFC 3339 format.
`data.updated_at`	string	Creation and last update times, using RFC 3339 format.

Error response¶

Response example

JSON
{
  "code": 2,
  "message": "<错误信息>"
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	The request body is invalid, the task is not a manually runnable enabled scheduled task, or the input does not meet the task constraints.	Check task status, triggering methods and inputs.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity has not been verified for workspace access and valid roles.	Use an identity and a valid role with access to the workspace.
`404`	`3`（`NOT_FOUND`）	The automated task does not exist.	Check the task details first.
`409`	`4`（`ALREADY_EXISTS`）	The task has conflicting activities running, or the task status conflicts.	Wait for the existing run to end or refresh the task status before trying again.
`503`	`15`（`UNAVAILABLE`）	Run executor, input snapshot or workflow submission services are temporarily unavailable.	Try again later.

Follow-up operations¶

Log data.id. Running a call does not mean it is finished. Use this ID to Query automation task running details to track the status; after entering the final state, Query the results of automated task execution.

Last updated on Sep 15, 2026