Steer a working run
/api/v1/runs/{run_id}/steeringSend a message to a run while it works. The run reads it before its next step and takes it into account, as if you had said it in a chat.
Only a pending or running agent run that no other run or workflow started takes a message. A run waiting for a question or tool approval does not; answer it through the run-interaction operation instead. A 409 with code run.not_steerable means the run cannot take a message now.
A 202 response means the message is stored, with status pending. Read the message again, or list the run's messages, to see whether the run read it (delivered) or ended first (undelivered). When the run is a chat's turn, a message it never read waits for the chat's next turn instead (requeued).
Send a client_ref to make retries safe: sending again with the same reference returns the stored message. Up to 20 messages may wait for a run at once; a 409 with code run.steering_full means you should wait until the run reads some.
Required access
Credentials: delegated token, user session, user API key
User API keys use the owner’s current permissions, subject to any key restrictions. Capability scopes below apply to automation account keys and delegated tokens.
Scope: runs:edit
Only the user who started the run may steer it, while an active workspace member who isn't a viewer, and a delegated token acts as that user. Workspace owners and admins cannot steer another user's run, and automation accounts cannot steer. A delegated token steering a chat's turn also needs chats:edit and agents:invoke, since a message the turn doesn't read becomes the chat's next turn; without them it answers 403.
A user-owned key prefixed gsmc_uk_, bound to one organization. It follows its owner's current membership, role and resource permissions, optionally restricted to read-only access. No X-Org-Id header is needed; a conflicting organization is rejected. Credential creation, personal connection setup and human attestations require a signed-in session. Runs are private to the calling user; sharing an agent grants access to your own personal memory of it, never to the agent's own memory.
In: header
Path Parameters
Header Parameters
Selects the active organization for a direct user session that has more than one membership. Automation account keys and delegated tokens are each bound to one organization and ignore it.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
A message for the run to read before its next step.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/runs/0/steering" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "Only cover the last quarter, and skip the appendix.", "client_ref": "retry-safe-7f3c" }'{ "message": { "id": 0, "run_id": 0, "status": "pending", "content": "string", "client_ref": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "delivered_at": "2019-08-24T14:15:22Z" }}