CreateCopilotSession - Alibaba Cloud Linux - Alibaba Cloud Documentation Center

Creates a Copilot session.

Operation description

This operation only creates a session. It does not send messages or trigger agent execution.
After the session is created, call GenerateCopilotStreamResponse with the returned sessionId to send messages.
The session ID is generated by the server and cannot be specified by the caller.
Each successful call creates an independent session. This operation does not provide client-side idempotency parameters. Repeated calls may create multiple sessions.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request syntax

POST /api/v1/copilot/sessions HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
body	object	No	The request body.
name	string	No	The session name. The name must be 1 to 255 characters in length. Default value: New Session. Empty strings or null values are not supported. If no name is specified, the server uses content generation to generate a session name based on the first user message when it is received.	Troubleshoot CPU load

Response elements

Element	Type	Description	Example
	object
code	string	The error code.	Success
data	object	The returned data.
activeTurn	object	The information about the current active execution.
createdAt	string	The time when the execution was created. The time follows the ISO 8601 standard and includes the time zone offset.	2026-10-29T10:01:00+08:00
finishedAt	string	The time when the execution ended. The time follows the ISO 8601 standard and includes the time zone offset. If the execution has not ended, the value is null.	2026-10-29T10:02:00+08:00
inputTokens	integer	The total number of input tokens consumed during this execution.	1200
outputTokens	integer	The total number of output tokens consumed during this execution.	80
pendingInputId	string	The ID of the form that is waiting for user input. Use this value when submitting user input. If no form is pending submission, the value is null.	form-001
status	string	The execution status.	running
turnId	string	The execution ID. Use this value when submitting user input, reconnecting to the event stream, or stopping the execution.	d71fc5ceac2949f39a264c8a585f3148
updatedAt	string	The time when the execution was updated. The time follows the ISO 8601 standard and includes the time zone offset.	2026-10-29T10:01:30+08:00
createdAt	string	The time when the session was created.	2026-10-29T10:00:00+08:00
cursor	string	The cursor of the latest persisted event in the session. For a newly created session that has no events, the value is "0". This field is a decimal string.	0
lastTurn	object	The information about the most recent execution.
createdAt	string	The time when the execution was created. The time follows the ISO 8601 standard and includes the time zone offset.	2026-10-29T10:01:00+08:00
finishedAt	string	The time when the execution ended. The time follows the ISO 8601 standard and includes the time zone offset. If the execution has not ended, the value is null.	2026-10-29T10:01:00+08:00
inputTokens	integer	The total number of input tokens consumed during this execution.	1200
outputTokens	integer	The total number of output tokens consumed during this execution.	80
pendingInputId	string	The ID of the form that is waiting for user input.	form-001
status	string	The execution status.	completed
turnId	string	The execution ID.	d71fc5ceac2949f39a264c8a585f3148
updatedAt	string	The time when the execution was updated. The time follows the ISO 8601 standard and includes the time zone offset.	2026-10-29T10:01:00+08:00
name	string	The session name. If no name is specified, the value is New Session.	Troubleshoot CPU load
scheduledTask	object	The information about the associated scheduled task.
runId	string	The ID of this scheduled execution. This ID is used to distinguish different trigger records of the same scheduled task.	run-example-001
scheduledAt	string	The scheduled trigger time. The time follows the ISO 8601 standard and includes the time zone offset.	2026-10-29T09:00:00+08:00
startedAt	string	The time when Copilot started processing this schedule. The time follows the ISO 8601 standard and includes the time zone offset.	2026-10-29T09:00:00+08:00
taskId	integer	The ID of the associated scheduled task.	42
taskName	string	The task name when the scheduled task was triggered. Subsequent changes to the task name do not change this value.	Daily inspection
timezone	string	The scheduling time zone of the scheduled task.	Asia/Shanghai
sessionId	string	The session ID. Use this value when sending messages, querying, updating, or deleting the session later.	c356bc310e4345c3a602a2912322ad21
sessionType	string	The session source. Valid values: openapi: API call. cron: scheduled task. im_dingtalk: DingTalk. im_feishu: Lark. alert: alert. Sessions created by this operation are of the openapi type.	openapi
status	string	The session status. The session created by this operation is active, which indicates that the session is available for use, but does not indicate that the agent is executing a task.	active
updatedAt	string	The time when the session was updated.	2026-10-29T10:00:00+08:00
message	string	The error message. If `code == Success`, this field is empty. Otherwise, this field contains the request error message.	""
requestId	string	The request ID, which can be used for end-to-end diagnostics.	5BC79EF5-798B-5499-9683-4E14EBBBF712

Examples

Success response

JSON format

{
  "code": "Success",
  "data": {
    "activeTurn": {
      "createdAt": "2026-10-29T10:01:00+08:00",
      "finishedAt": "2026-10-29T10:02:00+08:00",
      "inputTokens": 1200,
      "outputTokens": 80,
      "pendingInputId": "form-001",
      "status": "running",
      "turnId": "d71fc5ceac2949f39a264c8a585f3148",
      "updatedAt": "2026-10-29T10:01:30+08:00"
    },
    "createdAt": "2026-10-29T10:00:00+08:00\n",
    "cursor": "0",
    "lastTurn": {
      "createdAt": "2026-10-29T10:01:00+08:00",
      "finishedAt": "2026-10-29T10:01:00+08:00",
      "inputTokens": 1200,
      "outputTokens": 80,
      "pendingInputId": "form-001",
      "status": "completed",
      "turnId": "d71fc5ceac2949f39a264c8a585f3148",
      "updatedAt": "2026-10-29T10:01:00+08:00"
    },
    "name": "排查 CPU 负载",
    "scheduledTask": {
      "runId": "run-example-001",
      "scheduledAt": "2026-10-29T09:00:00+08:00",
      "startedAt": "2026-10-29T09:00:00+08:00",
      "taskId": 42,
      "taskName": "每日巡检",
      "timezone": "Asia/Shanghai"
    },
    "sessionId": "c356bc310e4345c3a602a2912322ad21",
    "sessionType": "openapi",
    "status": "active",
    "updatedAt": "2026-10-29T10:00:00+08:00"
  },
  "message": "\"\"",
  "requestId": "5BC79EF5-798B-5499-9683-4E14EBBBF712\n"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.