Skip to main content
POST
Start Check Run

Overview

Starts a check run for one environment. The server generates simulations_count conversations per configured scenario against the candidate version, scores each with the configured judges, and records a verdict. The run is returned immediately as PENDING, moves to RUNNING, and ends PASSED, FAILED, ERROR, or CANCELLED. Poll Get Check Run until the status is terminal, then gate your own publish or promote call on overall_passed. A check run never moves an environment pointer. The run freezes the config as it stands when it starts; later edits with Set Checks do not affect it. One run at a time per environment. Requires an admin, owner, operator, or prompter role.

Headers

string
required
Your API key for authentication.

Path Parameters

string
required
The agent’s unique identifier.
string
required
staging or production. Any other value returns 400 BAD_REQUEST.

Body Parameters

string
The version to score. Must be a version of this agent; any version qualifies, so you can re-check an older one. Omit it (or pass an empty string) to score what a promotion into this environment would deploy: for production, the version pinned to staging; for staging, the newest version saved on the main line. Returns 400 BAD_REQUEST when the ID is not a version of this agent, or when the default cannot be resolved (staging is unpinned, or the agent has no saved versions).

Response

Returns 202 with the new run. If the run could not be scheduled, the response is still 202 but the run’s status is ERROR with an error_message, so read the status rather than assuming PENDING. Returns 400 BAD_REQUEST when the environment has no check config, the config is disabled, or the config is no longer runnable (for example, a scenario was deleted). Returns 409 CONFLICT while another run for the same environment is PENDING or RUNNING; cancel it with Cancel Check Run or wait for it to finish.
object
The new check run.
null | array
null on success, or a list of error objects if the request failed.

Docs for agents: llms.txt