CreateCopilotSession

Updated at:

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, use the returned sessionId to call GenerateCopilotStreamResponse 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

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

sysom:CreateCopilotSession

create

*All Resource

*

None None

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 create a session name based on the first user message when it is received.

Troubleshoot CPU load

Response elements

Element

Type

Description

Example

object

requestId

string

The request ID, which can be used for end-to-end diagnostics.

5BC79EF5-798B-5499-9683-4E14EBBBF712

code

string

The error code.

Success

message

string

The error message.

  • If code == Success, this field is empty.

  • Otherwise, this field contains the request error message.

""

data

object

The returned data.

sessionId

string

The session ID. Use this value to send messages, query, update, or delete the session.

c356bc310e4345c3a602a2912322ad21

name

string

The session name. If not specified, the value is New Session.

Troubleshoot CPU load

status

string

The session status. The session created by this operation is active, which indicates that the session is available. It does not indicate that the agent is executing a task.

Valid values:

  • active
  • archived

active

activeTurn

object

The information about the current active execution.

turnId

string

The execution ID. Use this value to submit user input, reconnect to the event stream, or stop the execution.

d71fc5ceac2949f39a264c8a585f3148

status

string

The execution status.

running

pendingInputId

string

The ID of the form that is waiting for user input. Use this value when submitting user input. The value is null if no form is pending submission.

form-001

inputTokens

integer

The cumulative number of input tokens consumed by this execution.

1200

outputTokens

integer

The cumulative number of output tokens generated by this execution.

80

createdAt

string

The time when the execution was created. The time is in ISO 8601 format and includes the time zone offset.

2026-10-29T10:01:00+08:00

updatedAt

string

The time when the execution was updated. The time is in ISO 8601 format and includes the time zone offset.

2026-10-29T10:01:30+08:00

finishedAt

string

The time when the execution finished. The time is in ISO 8601 format and includes the time zone offset. The value is null if the execution has not finished.

2026-10-29T10:02:00+08:00

cursor

string

The cursor of the latest persisted event in the session. For a newly created session without events, 0 is returned. This field is a decimal string.

0

createdAt

string

The creation time.

2026-10-29T10:00:00+08:00

updatedAt

string

The update time.

2026-10-29T10:00:00+08:00

lastTurn

object

The information about the most recent execution.

turnId

string

The execution ID.

d71fc5ceac2949f39a264c8a585f3148

status

string

The execution status.

completed

pendingInputId

string

The ID of the form that is waiting for user input.

form-001

createdAt

string

The time when the execution was created. The time is in ISO 8601 format and includes the time zone offset.

2026-10-29T10:01:00+08:00

updatedAt

string

The time when the execution was updated. The time is in ISO 8601 format and includes the time zone offset.

2026-10-29T10:01:00+08:00

finishedAt

string

The time when the execution finished. The time is in ISO 8601 format and includes the time zone offset. The value is null if the execution has not finished.

2026-10-29T10:01:00+08:00

inputTokens

integer

The cumulative number of input tokens consumed by this execution.

1200

outputTokens

integer

The cumulative number of output tokens consumed by this execution.

80

sessionType

string

The session source. Valid values:

  • openapi: proactive call.

  • cron: scheduled task.

  • im_dingtalk: DingTalk.

  • im_feishu: Lark.

  • alert: alert. The session created by this operation is openapi.

openapi

scheduledTask

object

The information about the associated scheduled task.

taskId

integer

The ID of the associated scheduled task.

42

taskName

string

The task name when the scheduled task is triggered. Subsequent changes to the task name do not affect this value.

Daily inspection

runId

string

The ID of this scheduled execution, which is used to distinguish different trigger records of the same scheduled task.

run-example-001

scheduledAt

string

The scheduled trigger time. The time is in ISO 8601 format and includes the time zone offset.

2026-10-29T09:00:00+08:00

startedAt

string

The time when Copilot started processing this scheduled execution. The time is in ISO 8601 format and includes the time zone offset.

2026-10-29T09:00:00+08:00

timezone

string

The scheduling time zone of the scheduled task.

Asia/Shanghai

Examples

Success response

JSON format

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

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.