Outcomes

What is an outcome?

An outcome is the handler's report of what happened when it processed an execution. While CueAPI tracks delivery status (did the webhook return 200?), the outcome captures business status (did the handler actually succeed?).

Delivery vs. outcome

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:

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

On failure

{
  "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:

{
  "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