Skip to main content

Update session

Update session metadata, model, reasoning effort, and service tier; changes apply to later turns only.

Endpoint

POST /agents/sessions/{session_id} Returns 200 and the complete updated Session. Only metadata, agent.model, and agent.reasoning.effort can be updated. Updates affect later turns only. They do not change a running turn or write back to the saved agent. Concurrent update conflicts return 409 conflict_error; retrieve the latest state and retry.

Request body

metadata object / null (optional)Metadata, replaced as a whole, omitted keeps the current value, null or {} clears. Up to 16 items, key non-empty and up to 64 characters, value a string up to 512 charactersagent object (optional)Session-level settings, omitted keeps the current value, null is rejected, {} is valid but changes nothing. Unknown fields are rejected
model string (optional)Model for later turns, omitted keeps the current value, null or all whitespace is rejected. The update endpoint allows up to 1,048,576 characters, and a model change must use a model available in the current workspacereasoning object (optional)Can contain only effort, not summary, omitted keeps the current value, null is rejected
effort string / null (optional)Reasoning effort, none, minimal, low, medium, high, xhigh, max, or ultra; null resets to the model default
At least one of metadata and agent must be present. An empty request body, JSON null, or a request body of {} returns 400.agent: {} is valid by itself but does not change any setting. Update validates the settings before reading and merging the resource; if the settings are invalid and the resource does not exist at the same time, the API can return 400 first.

Request example

curl -sS -X POST "$BASE_URL/agents/sessions/sess_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"source": "updated"},
    "agent": {
      "model": "qwen3.8-max",
      "reasoning": {"effort": "medium"}
    }
  }'

Response fields

Returns the complete updated session object. null when the fields are incomplete.id stringSession ID; reuse it for follow-up turnsobject stringSession object type, fixed as agent.sessioncreated_at integerCreation time in Unix secondslast_active_at integerLast activity time in Unix seconds; not a version number or lockstatus stringSession status: idle, in_progress, requires_action, or failedagent objectEffective agent snapshot.
id stringAgent ID; inline configurations return a session snapshot ID, not a reusable saved agent, and it cannot be retrieved through Agent GETmodel stringModel IDinstructions string / nullCustom instructionsname string / nullDisplay namereasoning object / nullReasoning configuration, contains effort and summarytext object / nullText output configuration; contains format and verbositytools arrayTool configurationmulti_agent object / nullSubagent configuration; contains enabled and max_concurrent_subagents
environment objectSafe environment summary; only type for none.
type stringEnvironment type; none or openai_hostedid stringEnvironment ID, omitted when there is no authoritative valuestatus stringEnvironment status: omitted when there is no authoritative valueenvironment_template_id stringEnvironment template ID, omitted when there is no authoritative valueworkspace_directory stringWorkspace directory, omitted when there is no authoritative valueerror string / nullEnvironment error description, omitted when there is no authoritative valuedesktop object / nullDesktop settings; contains enabledcapability_directories array<string> / nullCapability discovery directoriesnetwork object / nullNetwork policy; contains access and allowed_domainspackages object / nullPackage lists; contains npm, python, and systemfiles arraySafe environment file metadataskills arraySafe skill metadataplugins arrayPlugin information; [] for managed environments
metadata objectSession metadata; an empty value is {}vault_ids array<string>Vault IDs recorded at creation; this does not mean mounting is completerequired_actions arrayFunction calls that need client handling; [] when empty.
type stringItem type, fixed as function_callturn_id stringPublic turn IDcall_id stringFunction call IDname stringFunction namearguments objectParsed call arguments
error string / nullSession-level error message, different from a turn's structured errorusage object / nullToken usage.
input_tokens integerNumber of input tokensinput_tokens_details objectInput token details.
cached_tokens integerNumber of input tokens that hit the cache
output_tokens integerNumber of output tokensoutput_tokens_details objectOutput token details.
reasoning_tokens integerNumber of reasoning tokens
total_tokens integerTotal number of tokens
spend_control objectSpend control; returned only when a historical record has a value; creation and update do not accept writes.
limit integerSpending limit in centsconsumed integer / nullConsumed amount in cents

Response example

{
  "id": "sess_xxx",
  "object": "agent.session",
  "created_at": 1794118835,
  "last_active_at": 1794119300,
  "status": "idle",
  "agent": {
    "id": "agent_xxx",
    "model": "qwen3.8-max",
    "instructions": "Answer briefly.",
    "reasoning": {"effort": "medium", "summary": "auto"},
    "text": {"format": {"type": "text"}, "verbosity": "medium"},
    "tools": [],
    "multi_agent": {"enabled": false, "max_concurrent_subagents": null},
    "name": null
  },
  "environment": {"type": "none"},
  "metadata": {"source": "updated"},
  "required_actions": [],
  "vault_ids": [],
  "error": null,
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 8,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 20
  }
}

Error codes

Business errors return an error object with type, code, message, and param. Common errors:
HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_errorSend at least one of metadata or agent in a valid JSON object
400invalid_request_error / unknown_parameter, invalid_type, invalid_valueRemove unknown fields and fix field types and enum values as described
400invalid_request_error / object_above_max_properties, empty_property_name, property_name_above_max_length, string_above_max_lengthShorten metadata or the string field as described
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
404not_found_error / not_found_errorUse a well-formed, non-archived session ID from the current workspace
409conflict_error / conflict_errorRetrieve the session again and retry
502server_error / agents_api_upstream_unavailableRetry later. If it keeps failing, submit a ticket with the x-request-id from the response headers