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.

tokens
object
required

Token totals for the run, summed over its samples when it finalized. Each is null when nothing reported that figure, which is a different fact from zero and must not render as free.

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