A Session combines an Agent (configuration) and an Environment (infrastructure) into a stateful execution context. You send messages to a Session, and it returns a stream of events.
The new Qoder CN documentation site is now available. Content on this site may not reflect the latest product features and changes. Visit docs.qoder.cn for the latest product documentation.
Session lifecycle
-
Create → idle
A new Session enters the
idlestate, waiting for input. -
idle → processing
After you send a
user.messageevent, the status changes toprocessing. -
processing → idle
When the current turn completes, the Session returns to the
idlestate, ready for the next turn. -
processing → canceling → idle
When you cancel a running Session, its status transitions to
cancelingbefore returning toidle. The Session remains available for use. -
archived (terminal state)
The
archivedstatus is a terminal state. An archived Session cannot be restored.
A Session is a state machine with the following core statuses:
|
Status |
Description |
Transitions to |
|
|
Idle, waiting for a user message. |
|
|
|
Processing; the Agent is running. |
|
|
|
Cancellation requested; waiting for the running task to stop. |
|
|
|
Archived. |
— (terminal state) |
Fields
|
Parameter |
Type |
Description |
|
|
string |
System-generated, with a |
|
|
string |
Fixed value: |
|
|
string/object |
The bound Agent. Use a string (Agent ID) for the latest version, or an object |
|
|
string |
The ID of the bound Agent. This field is returned only in the response and is retained for backward compatibility. |
|
|
string |
The ID of the bound Environment. |
|
|
string |
The current status: |
|
|
string |
The status of the current turn: |
|
|
string |
The title of the Session. Defaults to |
|
|
array |
A list of associated Memory Store IDs. Defaults to |
|
|
array |
A list of associated Vault IDs. Defaults to |
|
|
array |
Resources, such as files, attached to the Session. Defaults to |
|
|
string |
The time when the Session was created. |
|
|
string |
The time when the Session was last updated. |
The REST API response does not include token usage data (usage). It only appears in the session.status_idle Server-Sent Events (SSE) event at the end of each turn.
Create a session
To create a Session, specify an agent and an environment_id.
Use an Agent ID (string)
Binds the Session to the latest version of the Agent.
# Create a Session using an Agent ID
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"agent": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
"environment_id": "env_019e44eb66bb748cabcd1489f6fa4428"
}' | jq .
Use an Agent object (specify version)
Binds the Session to a specific version of the Agent for consistent behavior.
# Create a Session by specifying an Agent version
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
"version": 2
},
"environment_id": "env_019e44eb66bb748cabcd1489f6fa4428"
}' | jq .
A successful request returns a 201 Created response:
{
"id": "sess_019e5ce0bf9074b69c3481e93771a522",
"agent": {
"created_at": "2026-05-18T10:00:00Z",
"default_environment": "",
"description": "",
"id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
"instructions": "You are a code review expert.",
"mcp_servers": [],
"model": "ultimate",
"name": "code-reviewer",
"system": "You are a code review expert.",
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write"]
}
],
"type": "agent",
"updated_at": "2026-05-18T10:00:00Z",
"version": 2
},
"agent_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
"environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
"status": "idle",
"title": "",
"turn_status": "idle",
"memory_store_ids": [],
"resources": [],
"vault_ids": [],
"type": "session",
"created_at": "2026-05-18T12:00:00Z",
"updated_at": "2026-05-18T12:00:00Z"
}
In production, specify a version to prevent unexpected behavior changes from Agent updates.
Agent field format
|
Format |
Example |
Behavior |
|
string |
|
Uses the latest version of the Agent. |
|
object |
|
Locks the Session to the specified version. |
State transitions
Event request body format
The request body for POST /sessions/{id}/events must be an object containing an events array. Each event in the array includes a content field, which is an array of content blocks.
|
Parameter |
Type |
Required |
Description |
|
|
array |
Yes |
An array of events. A single request can contain one or more events. |
|
|
string |
Yes |
The event type, such as |
|
|
array |
Yes |
An array of content blocks. |
|
|
string |
Yes |
The content block type, such as |
|
|
string |
Yes |
The text content. |
idle → processing
When you send a user.message event to a Session, its status changes from idle to processing.
# Send a message to trigger processing
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/events" \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"events": [{
"type": "user.message",
"content": [{"type": "text", "text": "Analyze the code complexity of all Python files in the current directory."}]
}]
}' | jq .
processing → idle
When processing completes, the Session automatically returns to idle. You receive a session.status_idle event through the event stream.
Cancel a session
You can interrupt a running Session.
# Cancel a Session
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/cancel" \
-H "Authorization: Bearer $QODER_PAT"
A cancel request only interrupts execution if the Session is in the processing status. The status first transitions to canceling and then back to idle once the interruption is complete. The Session can be reused; simply send the next user.message to continue. Attempting to cancel a Session that is already idle has no effect. It returns a 200 OK response without changing the idle status.
Retrieve sessions
# Retrieve a single Session
curl -s "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522" \
-H "Authorization: Bearer $QODER_PAT"
# List all Sessions (with pagination)
curl -s "https://api.qoder.com.cn/api/v1/cloud/sessions?limit=10" \
-H "Authorization: Bearer $QODER_PAT"
Example paginated response:
{
"data": [
{
"id": "sess_019e5ce0bf9074b69c3481e93771a522",
"type": "session",
"agent_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
"environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
"status": "idle",
"turn_status": "idle",
"title": "",
"memory_store_ids": [],
"vault_ids": [],
"resources": [],
"created_at": "2026-05-18T12:00:00Z",
"updated_at": "2026-05-18T12:30:00Z"
}
],
"first_id": "sess_019e5ce0bf9074b69c3481e93771a522",
"last_id": "sess_019e5ce0bf9074b69c3481e93771a522",
"has_more": false
}
Token usage
Per-turn token usage is not returned through the REST API. Instead, listen for the session.status_idle SSE event at the end of each turn. Its usage field contains the token counts for that turn.
|
Parameter |
Description |
|
|
The number of input tokens consumed in this turn. |
|
|
The number of output tokens generated in this turn. |
|
|
The number of input tokens served from the cache. |
|
|
The number of input tokens written to the cache. |
Example session.status_idle SSE payload:
{
"type": "session.status_idle",
"usage": {
"input_tokens": 3840,
"output_tokens": 2156,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0
}
}
Session and Agent version binding
A Session snapshots the Agent configuration at creation time.
-
Use the string format
"agent": "agent_xxx"to bind to the latest version of the Agent at the time of creation. -
Use the object format
"agent": {"id": "agent_xxx", "version": N}to bind to a specific version. -
After a Session is created, modifying the Agent does not affect that Session.
-
To use a new version of an Agent, you must create a new Session.
Session A — Bound to Agent v1Created before the update. Session A continues to use the v1 configuration even after the Agent is updated to v2. |
Session B — Bound to Agent v2Created after the update. It uses the new v2 configuration. |
Multi-turn conversation
Sessions support multi-turn conversation. After sending a message, wait for the session.status_idle event before sending the next message.
#!/bin/bash
# Multi-turn conversation example
BASE_URL="https://api.qoder.com.cn/api/v1/cloud"
SESSION_ID="sess_019e5ce0bf9074b69c3481e93771a522"
HEADERS=(
-H "Authorization: Bearer $QODER_PAT"
)
# Turn 1: Make the initial request
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
"${HEADERS[@]}" \
-H "Content-Type: application/json" \
-d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "Create a Python Flask project scaffold."}]}]}'
# Wait for processing to complete... (poll or listen for SSE)
sleep 30
# Turn 2: Add a follow-up requirement
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
"${HEADERS[@]}" \
-H "Content-Type: application/json" \
-d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "Add unit tests and a CI configuration to the project."}]}]}'
Status-related error codes
Common errors when sending events to a Session:
|
HTTP |
Type |
Trigger condition |
|
409 |
|
Sending a message to a Session in the |
|
404 |
|
The Session does not exist or has been deleted. |
Example 409 error response:
{
"type": "error",
"error": {
"type": "conflict_error",
"message": "Session is currently processing a turn. Cancel the current turn or wait for completion."
}
}
Best practices
-
Version locking — In production environments, always create Sessions by using the
{"id": ..., "version": ...}format. -
Timely cancellation — Cancel unneeded Sessions to release resources.
-
Monitor usage — Regularly check the
usagefield to avoid unexpected costs. -
Tag with metadata — Use the
metadatafield to record business context, such as task IDs or trigger sources.
FAQ
Q: Do Sessions have a timeout mechanism?
A: An idle Session is retained for a period of time. Sessions inactive for an extended period may be automatically archived. Create Sessions on demand and cancel them after tasks complete.
Q: What happens if I send a message to a Session that is in the processing status?
A: The API returns an HTTP 409 conflict_error. Cancel the current turn or wait for the Session to return to idle before sending a new message.
Q: What is the maximum number of turns a Session supports?
A: No hard limit, but the model's context window size imposes a practical limit. As the conversation grows, earlier content may be truncated.
Q: How do I get the complete conversation history of a Session?
A: Call the GET /sessions/{id}/events operation to retrieve all events for the Session, including user messages and Agent responses.
Q: Can a canceled Session be reused?
A: Yes. After you cancel a Session, its status automatically transitions from canceling back to idle, and the Session remains available. You can send the next user.message to continue the conversation. Only the archived status is a terminal state. An archived Session cannot be restored.