Skip to main content
POST
Typescript (SDK)

Authorizations

Authorization
string
header
required

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

X-On-Behalf-Of
string

Optional external end-user identifier forwarded by the API gateway.

Path Parameters

agent_id
string
required

Body

application/json
input
required
Required string length: 1 - 20000
idempotency_key
string

Caller-scoped key for retrying the same submission without starting another run. Reusing a key with a different request returns 409.

Required string length: 1 - 255
agent_version
integer

Immutable saved-agent configuration version to execute. Omit to use the current version. Explicit versions remain pinned while queued.

Required range: 1 <= x <= 2147483647
conversation
any

Arbitrary JSON value.

previous_response_id
string
context_management
object[]

Context management strategies to apply during agent-run response generation. Supports compaction, which summarizes older conversation history when the context exceeds a token threshold.

stream
boolean
default:false

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.

metadata
object

Response

Queued run.

object
enum<string>
required
Available options:
agent.run
id
string
required
agent_id
string
required
agent_version
integer | null
required

The agent configuration version this run executed against. Null for runs created before versioning.

Required range: x >= 1
status
enum<string>
required

waiting 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.

Available options:
waiting,
queued,
submitting,
completed,
failed,
cancelled,
incomplete
input
any
required

Arbitrary JSON value.

conversation
any | null
required

Arbitrary JSON value.

previous_response_id
string | null
required
metadata
object | null
required
gateway_response_id
string | null
required
gateway_response
any | null
required

Arbitrary JSON value.

error
any | null
required

Arbitrary JSON value.

created_at
string<date-time>
required
completed_at
string<date-time> | null
required