Report run lifecycle events for a managed_by = 'standalone' agent. The platform stores the event for monitoring; it does not trigger or schedule the agent.
Endpoint
POST /api/agents/{agentId}/runs/ingest
Auth: Authorization: Bearer <ingest_api_key>
Request
json
{
"externalRunId": "exec_2024_03_15_001",
"status": "completed",
"startedAt": "2026-03-15T12:00:00.000Z",
"completedAt": "2026-03-15T12:01:30.000Z",
"durationMs": 90000,
"output": { "pages_processed": 42 },
"outputs": 42,
"metadata": { "version": "1.2.3" }
}
| Field | Type | Required | Description |
|---|---|---|---|
externalRunId | string | yes | Stable runtime-side identifier. Idempotency key. |
status | enum | yes | See Status values. |
startedAt | ISO 8601 | no | When execution started. |
completedAt | ISO 8601 | no | When execution ended (set on terminal states). |
durationMs | number | no | Total duration in milliseconds. |
output | object | no | Domain payload. |
outputs | integer | no | Count of agent-defined output units (drives ROI metrics). |
error | string | no | Error message — set when status='failed'. Max 4096 chars. |
metadata | object | no | Free-form metadata. |
userId | uuid | no | Attribution for runs.created_by, applied only on the first call for a given externalRunId; ignored on later status updates. Must be a member of the agent's organization (or a platform admin); unknown / non-member values are dropped silently and the run is still created with no creator. |
Status values
| Status | Meaning |
|---|---|
queued | Run has been accepted but execution has not started yet. |
running | Execution is in progress. |
completed | Terminal — finished successfully. Include output to surface results in run detail. |
failed | Terminal — errored. Include error with the failure reason. |
cancelled | Terminal — cancelled before completion. |
Idempotency and state transitions
- Idempotent on
(agentId, externalRunId). Repeated calls update the existing run. - Backward state transitions are rejected with
409 Conflict. For example, once a run reportscompleted, subsequent calls withstatus='running'will fail.
Response — 200 OK
json
{
"runId": 1234,
"status": "created"
}
| Field | Type | Description |
|---|---|---|
runId | number | Platform-side run identity. |
status | "created" | "updated" | Whether this call created a new row or updated an existing one. |
SDK
ts
import { ingestRun } from '@cxpa/sdk/agent'
await ingestRun({
baseUrl: process.env.CXPA_API_URL!,
ingestApiKey: process.env.CXPA_INGEST_KEY!,
agentId: 42,
externalRunId: 'exec_2024_03_15_001',
status: 'completed',
output: { pages_processed: 42 },
outputs: 42,
userId: '00000000-0000-4000-8000-000000000000', // optional, first call only
})