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 bodymetadataobject / 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
Properties 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
Properties effort string / null (optional)Reasoning effort, none, minimal, low, medium, high, xhigh, max, or ultra; null resets to the model defaultmetadata 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 |
Response fieldsReturns 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.
Properties 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_subagentsobjectSafe environment summary; only type for none.
Properties 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 environmentsobjectSession 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.
Properties type stringItem type, fixed as function_callturn_id stringPublic turn IDcall_id stringFunction call IDname stringFunction namearguments objectParsed call argumentsstring / nullSession-level error message, different from a turn's structured errorusage object / nullToken usage.
Properties input_tokens integerNumber of input tokensinput_tokens_details objectInput token details.
Properties cached_tokens integerNumber of input tokens that hit the cacheintegerNumber of output tokensoutput_tokens_details objectOutput token details.
Properties reasoning_tokens integerNumber of reasoning tokensintegerTotal number of tokensobjectSpend control; returned only when a historical record has a value; creation and update do not accept writes.
Properties limit integerSpending limit in centsconsumed integer / nullConsumed amount in cents | Response example |
Error codes
Business errors return an error object with type, code, message, and param. Common errors:
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / invalid_request_error | Send at least one of metadata or agent in a valid JSON object |
400 | invalid_request_error / unknown_parameter, invalid_type, invalid_value | Remove unknown fields and fix field types and enum values as described |
400 | invalid_request_error / object_above_max_properties, empty_property_name, property_name_above_max_length, string_above_max_length | Shorten metadata or the string field as described |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
404 | not_found_error / not_found_error | Use a well-formed, non-archived session ID from the current workspace |
409 | conflict_error / conflict_error | Retrieve the session again and retry |
502 | server_error / agents_api_upstream_unavailable | Retry later. If it keeps failing, submit a ticket with the x-request-id from the response headers |