Delete a session, stop execution, and remove public history; returns 409 while cleanup is incomplete.
Endpoint
DELETE /agents/sessions/{session_id}
Returns 200 and a delete envelope. Deletion stops the session's execution, closes input acceptance, and removes public history.
If cleanup is incomplete, the API returns 409 conflict_error; retry the same request. After deletion completes, repeating DELETE still returns 200 with the delete envelope, while GET returns 404. An unknown session ID or a cross-workspace DELETE returns 404.
Path parameterssession_idstring (required)Session ID. Treat it as an opaque stringThis endpoint has no request body or query parameters. | Request example |
Response fieldsidstringID of the deleted sessionobject stringSession deletion result object type, fixed as agent.session.deleteddeleted booleanWhether deletion succeeded, true when deletion succeeds | 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 | Pass a valid session ID in the expected format |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
404 | not_found_error / not_found_error | Use a non-archived session ID from the current workspace |
409 | conflict_error / conflict_error | Retry the same request |
503 | server_error / agents_api_upstream_unavailable | Retry later. If it keeps failing, submit a ticket with x-request-id |