Start a saved agent run
Starts an asynchronous background run for a saved agent and returns the queued run record. Use the run retrieval endpoint to poll status or the events endpoint to stream progress. When the agent is already running max_concurrent_runs runs, concurrency_overflow decides: reject returns 429 with error code agent_concurrency_limit and creates no run; queue returns 202 with a waiting run that starts when a slot frees.
Authorizations
Send Authorization: Bearer , using an MKA1 API key for automation or an OAuth API access token for a signed-in application. Use a dynamic security callback to refresh OAuth access tokens. Browser session-only operations still require their declared cookie.
Headers
Optional external end-user identifier forwarded by the API gateway.
Path Parameters
Body
1 - 20000Caller-scoped key for retrying the same submission without starting another run. Reusing a key with a different request returns 409.
1 - 255Immutable saved-agent configuration version to execute. Omit to use the current version. Explicit versions remain pinned while queued.
1 <= x <= 2147483647Arbitrary JSON value.
Context management strategies to apply during agent-run response generation. Supports compaction, which summarizes older conversation history when the context exceeds a token threshold.
When true, the gateway generates per-token delta events for this run, so the events endpoint streams incremental output instead of only item and lifecycle boundaries. The run still executes in the background and this endpoint still returns the queued run record.
Response
Queued run.
agent.run The agent configuration version this run executed against. Null for runs created before versioning.
x >= 1waiting means the run is held for one of the agent's max_concurrent_runs slots and has not been sent to the model; it can be cancelled. Terminal outcomes stay distinct: cancelled is caller-requested; incomplete means a limit or interruption stopped the run. gateway_response.incomplete_details records the reason, including max_tokens or max_tool_calls. Stored failed rows with one of these gateway outcomes are serialized with the gateway outcome, retaining any connector error and completion timestamp.
waiting, queued, submitting, completed, failed, cancelled, incomplete Arbitrary JSON value.
Arbitrary JSON value.
Arbitrary JSON value.
Arbitrary JSON value.