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.

Body

application/json
suite_id
string
required

Existing suite to import into. Its manifest defines the task set, so create the suite first.

Minimum string length: 1
agent_name
string
required

The harness agent, e.g. omp.

Required string length: 1 - 128
model
string
required
Required string length: 1 - 255
suite_version
integer

Defaults to the suite's active version.

Required range: 1 <= x <= 2147483647
agent_version
string | null
Maximum string length: 64
agent_effort
string | null

Reasoning-effort setting, e.g. medium. Part of the leaderboard's row identity, so the same agent and model at two efforts stay two rows.

Maximum string length: 32
cost_usd
number | null

Total spend for the job. Falls back to the sum of the trials' own costs when omitted.

Required range: x >= 0
created_at
integer

When the job ran, unix seconds. Defaults to now — set it when backfilling, since the board orders by this.

Required range: -9007199254740991 < x <= 9007199254740991
metadata
object
idempotency_key
string

Reusing a key returns the run created the first time instead of importing a second copy. Without one, a retried upload silently doubles the trials behind a board row.

Required string length: 1 - 255
trials
object[]

May be empty when opening a run to stream trials into. A one-shot import sends them all here.

Maximum array length: 1000
expected_trials
integer

How many trials the job will produce. Sets the run's total up front so the console shows real progress (12/89) while it streams, instead of 12/12 that grows.

Required range: 0 <= x <= 1000
finalize
boolean
default:true

False opens the run in_progress for POST /evals/runs/{run_id}/trials to fill. Leaderboards only count completed runs, so a streaming run stays off the board until it is finalized.

Response

200 - application/json

OK

id
string
required
object
any
required
suite_id
string
required
suite_version
integer
required
Required range: -9007199254740991 <= x <= 9007199254740991
suite_version_id
string
required
org_id
string
required

The org that owns this run.

team_id
string
required

The team that owns this run.

status
enum<string>
required
Available options:
queued,
in_progress,
finalizing,
completed,
failed,
cancelling,
cancelled
models
string[]
required
task_ids
string[] | null
required
judge_model
string | null
required
embedding_model
string | null
required
generation
object
required
request_counts
object
required
metrics
object | null
required
error
object | null
required
artifact_file_ids
string[]
required
metadata
object
required
agent_name
string | null
required

Coding-agent harness that produced this run (e.g. omp, claude-code). Null for every non-harness eval kind — a null here is not a missing value, it means the run is not an agent run.

agent_version
string | null
required

Version of agent_name, as the harness reported it. Null when agent_name is.

agent_effort
string | null
required

Reasoning-effort setting the agent ran at (e.g. medium, xhigh). Part of the leaderboard's row identity: the same agent and model at two efforts are two rows, not one. Null when agent_name is.

cost_usd
number | null
required

Total spend for the run in USD. Null when the harness did not report cost.

created_at
integer
required
Required range: -9007199254740991 <= x <= 9007199254740991
started_at
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991
completed_at
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991
cancelled_at
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991
failed_at
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991