Skip to main content

Delete session

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 parameters

session_id string (required)Session ID. Treat it as an opaque stringThis endpoint has no request body or query parameters.

Request example

curl -sS -X DELETE "$BASE_URL/agents/sessions/sess_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

Response fields

id stringID of the deleted sessionobject stringSession deletion result object type, fixed as agent.session.deleteddeleted booleanWhether deletion succeeded, true when deletion succeeds

Response example

{
  "id": "sess_xxx",
  "object": "agent.session.deleted",
  "deleted": true
}

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_errorPass a valid session ID in the expected format
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
404not_found_error / not_found_errorUse a non-archived session ID from the current workspace
409conflict_error / conflict_errorRetry the same request
503server_error / agents_api_upstream_unavailableRetry later. If it keeps failing, submit a ticket with x-request-id