Outcomes

The fourth coordination primitive. A write-once report of what happened.

What is an outcome?

An outcome is the fourth of CueAPI's five coordination primitives: a write-once report of what happened. Delivery answers "did the webhook return 200?" Outcome answers "did the work actually succeed?" One is set by CueAPI. The other is set by your handler. Both are required to verify a handoff end to end.

Delivery vs. outcome

	Delivery status	Outcome
Who sets it	CueAPI (automatic)	Your handler (explicit)
What it tracks	Was the payload delivered?	Did the work succeed?
Example	HTTP 200 OK	"Report generated, 847 chars"
Required	Always set	Optional

A delivery can succeed (HTTP 200) but the outcome can be a failure (handler encountered an error). Outcomes give you visibility into what your handler actually did.

Reporting an outcome

After your handler processes an execution, report the outcome:

bash

curl -X POST https://api.cueapi.ai/v1/executions/{execution_id}/outcome \
  -H "Authorization: Bearer cue_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "success": true,
    "result": "Report generated successfully",
    "metadata": {
      "rows_processed": 142,
      "duration_ms": 3200
    }
  }'

Request fields

Field	Type	Required	Description
`success`	boolean	Yes	Did the handler succeed?
`result`	string	No	Success message or output summary
`error`	string	No	Error message on failure
`metadata`	object	No	Structured data (max 10KB)

On failure

json

{
  "success": false,
  "error": "Database connection timeout after 30s",
  "metadata": {
    "retry_suggested": true,
    "error_code": "DB_TIMEOUT"
  }
}

Write-once

Outcomes are write-once. You can only report one outcome per execution. Attempting to report a second outcome returns 409 Conflict.

This prevents race conditions and ensures a single source of truth for each execution's result.

Outcome in execution response

Outcomes appear as a nested object when you fetch a cue's details:

json

{
  "executions": [
    {
      "id": "exec-uuid",
      "status": "success",
      "outcome": {
        "success": true,
        "result": "Report generated",
        "metadata": {"rows": 142},
        "recorded_at": "2026-03-13T09:01:23Z"
      }
    }
  ]
}

If no outcome was reported, the outcome field is null.

Worker transport outcomes

For worker transport cues, reporting an outcome also completes the execution lifecycle:

success: true → execution status set to success, cue run_count incremented
success: false → execution status set to failed

Note

For webhook transport, the delivery status is set automatically based on HTTP response codes. Outcomes are supplementary. For worker transport, outcomes are the primary mechanism for completing executions.

Previous← Executions NextTransport →