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. |
| queueWhenCapacityUnavailable | boolean | No | Persist the Evaluation run in Batches when runtime capacity is unavailable. Defaults to true on local appliances and false on cloud deployments. |
| queue_when_capacity_unavailable | boolean | No | Legacy alias for queueWhenCapacityUnavailable. |
What the API returns
Each response code below includes the documented payload shape for the ACP API.
202Evaluation run created or durably deferred to Batchesapplication/json
| Field | Type | Required | Description |
|---|---|---|---|
| run | object | Yes | — |
| run.id | string | Yes | Unique identifier. |
| run.checkpointCount | integer | No | Number of durably accepted cases; not a quality score. |
| run.summaryView | boolean | No | True for compact run listings without case payloads or evidence. |
| run.totalCount | integer | No | — |
| run.scoredCount | integer | No | — |
| run.passedCount | integer | No | — |
| run.failedCount | integer | No | — |
| run.errorCount | integer | No | — |
| run.skippedCount | integer | No | — |
| run.missingCount | integer | No | — |
| run.evaluationId | string | No | — |
| run.targetType | agent | function | metronome | service_topology | none | No | — |
| run.targetId | string | No | — |
| run.targetVersionId | string | No | — |
| run.targetVersionNumber | integer | No | — |
| run.targetInvocation | object | No | — |
| run.targetInvocation.method | GET | POST | PUT | PATCH | DELETE | No | — |
| run.targetInvocation.path | string | No | Workspace-relative file path. |
| run.targetInvocation.timeoutMs | integer | No | — |
| run.agentId | string | No | Agent ID. |
| run.environmentId | string | No | Computer ID. |
| run.versionId | string | No | — |
| run.purpose | diagnostic | development | optimization | release | external_validation | No | — |
| run.status | queued | running | completed | completed_with_errors | failed | cancelled | Yes | Current lifecycle status. |
| run.averageScore | number | No | — |
| run.passRate | number | No | — |
| run.costUsd | number | No | — |
| run.runFingerprint | string | No | — |
| run.evidence | object | No | — |
| run.evidence.schemaVersion | computer_agents_evaluation_run_evidence_v2 | Yes | — |
| run.evidence.runId | string | Yes | — |
| run.evidence.evaluation | object | Yes | — |
| run.evidence.evaluation.id | string | Yes | Unique identifier. |
| run.evidence.evaluation.versionId | string | Yes | — |
| run.evidence.evaluation.versionNumber | integer | Yes | — |
| run.evidence.evaluation.purpose | diagnostic | development | optimization | release | external_validation | Yes | — |
| run.evidence.evaluation.evaluationFingerprint | string | Yes | — |
| run.evidence.evaluation.datasetFingerprint | string | Yes | — |
| run.evidence.target | object | Yes | — |
| run.evidence.target.bindingStatus | control_plane_pinned | legacy_unverified | Yes | — |
| run.evidence.target.agentId | string | Yes | Agent ID. |
| run.evidence.target.agentVersionId | string | Yes | — |
| run.evidence.target.agentVersionNumber | integer | Yes | — |
| run.evidence.target.agentVersionStatus | string | Yes | — |
| run.evidence.target.targetType | agent | function | metronome | service_topology | none | Yes | — |
| run.evidence.target.targetId | string | Yes | — |
| run.evidence.target.targetVersionId | string | Yes | — |
| run.evidence.target.targetVersionNumber | integer | Yes | — |
| run.evidence.target.targetFingerprint | string | Yes | — |
| run.evidence.executionContext | object | Yes | — |
| run.evidence.executionContext.environmentId | string | Yes | Computer ID. |
| run.evidence.status | completed | completed_with_errors | failed | cancelled | Yes | Current lifecycle status. |
| run.evidence.metrics | object | Yes | — |
| run.evidence.metrics.totalCount | integer | Yes | — |
| run.evidence.metrics.reportedCount | integer | Yes | — |
| run.evidence.metrics.scoredCount | integer | Yes | — |
| run.evidence.metrics.passedCount | integer | Yes | — |
| run.evidence.metrics.failedCount | integer | Yes | — |
| run.evidence.metrics.errorCount | integer | Yes | — |
| run.evidence.metrics.skippedCount | integer | Yes | — |
| run.evidence.metrics.missingCount | integer | Yes | — |
| run.evidence.metrics.averageScore | number | Yes | — |
| run.evidence.metrics.passRate | number | Yes | — |
| run.evidence.cost | object | Yes | — |
| run.evidence.cost.usd | number | Yes | — |
| run.evidence.cost.legacyComputeTokens | number | Yes | — |
| run.evidence.evaluator | object | Yes | — |
| run.evidence.evaluator.evaluatorFingerprint | string | Yes | — |
| run.evidence.evaluator.systemFingerprint | string | Yes | — |
| run.evidence.generatedAt | string | Yes | — |
| run.evidence.resultSetFingerprint | string | Yes | — |
| run.evidence.reportFingerprint | string | Yes | — |
| run.evidence.provenance | object | Yes | — |
| run.evidence.provenance.schemaVersion | computer_agents_evaluation_run_evidence_provenance_v1 | Yes | — |
| run.evidence.provenance.source | execution_worker | api_client | computer_agents_thread | legacy_import | Yes | — |
| run.evidence.provenance.trustLevel | self_reported | verified_worker | Yes | — |
| run.evidence.provenance.verificationStatus | unverified | verified | Yes | — |
| run.evidence.provenance.executor | object | Yes | — |
| run.evidence.provenance.executor.kind | string | Yes | — |
| run.evidence.provenance.executor.id | string | Yes | Unique identifier. |
| run.evidence.provenance.attestation | object | Yes | — |
| run.evidence.provenance.attestation.schemaVersion | computer_agents_evaluation_execution_attestation_v1 | Yes | — |
| run.evidence.provenance.attestation.attestationId | string | Yes | — |
| run.evidence.provenance.attestation.workerId | string | Yes | — |
| run.evidence.provenance.attestation.dispatchId | string | Yes | — |
| run.evidence.provenance.attestation.workerAssertionId | string | Yes | — |
| run.evidence.provenance.attestation.credentialId | string | Yes | — |
| run.evidence.provenance.attestation.claimAttempt | integer | Yes | — |
| run.evidence.provenance.attestation.runId | string | Yes | — |
| run.evidence.provenance.attestation.evaluationId | string | Yes | — |
| run.evidence.provenance.attestation.evaluationVersionId | string | Yes | — |
| run.evidence.provenance.attestation.evaluationFingerprint | string | Yes | — |
| run.evidence.provenance.attestation.datasetFingerprint | string | Yes | — |
| run.evidence.provenance.attestation.targetType | agent | function | metronome | service_topology | none | Yes | — |
| run.evidence.provenance.attestation.targetId | string | Yes | — |
| run.evidence.provenance.attestation.targetVersionId | string | No | — |
| run.evidence.provenance.attestation.targetAgentId | string | No | — |
| run.evidence.provenance.attestation.targetAgentVersionId | string | No | — |
| run.evidence.provenance.attestation.targetFingerprint | string | Yes | — |
| run.evidence.provenance.attestation.environmentId | string | No | Computer ID. |
| run.evidence.provenance.attestation.resultSetFingerprint | string | Yes | — |
| run.evidence.provenance.attestation.reportFingerprint | string | Yes | — |
| run.evidence.provenance.attestation.issuedAt | string | Yes | — |
| run.evidence.provenance.attestation.verifiedAt | string | Yes | — |
| run.evidence.results | object[] | Yes | — |
| run.evidence.results[].caseId | string | Yes | — |
| run.evidence.results[].name | string | No | Human-readable name. |
| run.evidence.results[].status | passed | failed | error | skipped | Yes | Current lifecycle status. |
| run.evidence.results[].score | number | No | — |
| run.evidence.results[].output | object | No | — |
| run.evidence.results[].explanation | string | No | — |
| run.evidence.results[].error | string | No | — |
| run.evidence.results[].durationMs | integer | No | — |
| run.evidence.results[].evaluator | object | No | — |
| run.evidence.results[].metadata | object | No | Free-form metadata object. |
| run.evidence.fingerprint | string | Yes | — |
| run.evidence.signature | object | No | — |
| run.evidence.signature.schemaVersion | computer_agents_evaluation_evidence_signature_v1 | Yes | — |
| run.evidence.signature.provider | google_cloud_kms | Yes | — |
| run.evidence.signature.keyVersion | string | Yes | — |
| run.evidence.signature.algorithm | string | Yes | — |
| run.evidence.signature.signedFingerprint | string | Yes | — |
| run.evidence.signature.signature | string | Yes | — |
| run.evidence.signature.signedAt | string | Yes | — |
| run.evidenceSchemaVersion | string | No | — |
| run.evidenceFingerprintVerified | boolean | No | — |
| run.evidenceSource | string | No | — |
| run.evidenceTrustLevel | string | No | — |
| run.evidenceVerificationStatus | string | No | — |
| run.evidenceProvenanceVerified | boolean | No | — |
| run.evidenceAttestationId | string | No | — |
| run.evidenceSignatureStatus | unsigned | kms_signed | invalid | No | — |
| run.evidenceSignatureKeyVersion | string | No | — |
| run.evidenceSignatureAlgorithm | string | No | — |
| run.createdAt | string | No | ISO 8601 timestamp. |
| run.updatedAt | string | No | ISO 8601 timestamp. |
| run.completedAt | string | No | ISO 8601 timestamp. |