Create an evaluation run
POST
/v1/evaluations/{evaluationId}/runsHow to call this endpoint
Every ACP API request uses bearer authentication. The examples here show the actual request path, auth header, and body shape that the platform expects.
Path, query, and header parameters
These parameters control which ACP object the endpoint acts on and how the request is processed.
Path parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
| evaluationId | path | string | Yes | — |
Query parameters
None.
Body schema
Content type: application/json · Required
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | No | Unique identifier. |
| runId | string | No | — |
| run_id | string | No | — |
| target | object | No | The platform resource evaluated by this run. Agent, Function, and Metronome targets require `id`. A service_topology requires `entrypoint` and one or more uniquely-keyed `resources`; the complete topology is pinned before dispatch and the entrypoint is invoked. Agent resources require immutable `versionId` values and a Metronome entrypoint so the runtime can enforce and attest their exact versions. A direct Agent target also requires `environmentId`; when `versionId` is omitted, the control plane pins the latest published Agent version or rejects the run before dispatch. An explicitly requested saved Function or Metronome `versionId` is eligible only when it belongs to a registered immutable Optimization Candidate; ordinary saved drafts are rejected. Saved Function candidates execute only through the networkless Evaluation sandbox and never through the live deployment. An unpublished saved Agent version additionally requires `candidateAuthority`, bound to the completed Agent Optimization job that owns that exact version. |
| target.kind | agent | function | metronome | service_topology | Yes | — |
| target.id | string | No | Unique identifier. |
| target.targetId | string | No | — |
| target.versionId | string | No | — |
| target.candidateAuthority | object | No | Canonical authority for evaluating an unpublished saved Agent version. The Evaluation service verifies that the completed Agent Optimization job owns the exact candidate version and carries a successful, evidence-bound publication decision before dispatch. |
| target.candidateAuthority.kind | agent_optimization_job | Yes | — |
| target.candidateAuthority.id | string | Yes | Unique identifier. |
| target.environmentId | string | No | Computer ID. |
| target.invocation | object | No | — |
| target.invocation.method | GET | POST | PUT | PATCH | DELETE | No | — |
| target.invocation.path | string | No | Workspace-relative file path. |
| target.invocation.timeoutMs | integer | No | — |
| target.entrypoint | string | No | — |
| target.resources | object[] | No | — |
| target.resources[].key | string | Yes | — |
| target.resources[].kind | agent | function | metronome | Yes | — |
| target.resources[].id | string | Yes | Unique identifier. |
| target.resources[].versionId | string | No | — |
| target.resources[].candidateAuthority | object | No | Canonical authority for evaluating an unpublished saved Agent version. The Evaluation service verifies that the completed Agent Optimization job owns the exact candidate version and carries a successful, evidence-bound publication decision before dispatch. |
| target.resources[].candidateAuthority.kind | agent_optimization_job | Yes | — |
| target.resources[].candidateAuthority.id | string | Yes | Unique identifier. |
| agentId | string | No | Agent ID. |
| environmentId | string | No | Computer ID. |
| computerId | string | No | — |
| versionId | string | No | — |
| label | string | No | — |
| purpose | diagnostic | development | optimization | release | external_validation | No | — |
| metadata | object | No | Free-form metadata object. |
| run | object | No | Execution configuration metadata. Version and dataset binding fields are server-owned and cannot be overridden. |
What the API returns
Each response code below includes the documented payload shape for the ACP API.
202Queued evaluation run
None.