Skip to main content
POST
Python (SDK)

Authorizations

Authorization
string
header
required

Gateway auth: send Authorization: Bearer <mka1-api-key>. For multi-user server-side integrations, you can also send X-On-Behalf-Of: <external-user-id>.

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
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
Available options:
queued,
submitting,
completed,
failed
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