goal-runs
Create Goal Run
Create one singleton Goal Run for a published Goal.
In a delivery-confirmation integration, phone identifies one customer and variables
provide that order's reference and proposed window. CALL-E atomically resolves and pins the
published RunSpec, validates the variables, and durably accepts execution.
The request cannot select, replace, or relax schemas or the materialization contract. The
first accepted request and an exact idempotent replay both return 201 with the same Goal
Run identity. A 201 response means durable acceptance, not that the recipient answered or
that result is ready.
path Parameters
goal_idOpaque public Goal identity returned by CALL-E Chat publish success or GET /v1/goals.
Store it with your integration configuration. It identifies the reusable Goal and is
different from published_run_spec.id, goal_run_id, and the nested telephone run_id.
Headers
Idempotency-KeyRequired business-stable identity for one logical Goal Run, scoped to the authenticated
owner and goal_id. Derive it from a durable workflow event, for example
delivery:ORD-8472:confirm-window:v1, and persist it before sending the request.
Retry a timeout with the same key and the same canonical request. An exact replay returns
the original Goal Run with 201; changing the phone or variables while reusing the key
returns 409 idempotency_conflict. Do not generate a new random key for each network retry.
Create Goal Run › Request Body
phone^\+[1-9]\d{7,14}$ · requiredRecipient phone in canonical E.164 form: +, country code, and subscriber number with
no spaces, punctuation, or extension. The caller must be authorized to contact it.
CALL-E validates it against the published Goal's fixed Voice Target policy.
Per-Run business context validated against the pinned published input_schema. Keys and
required fields vary by Goal. Values must be finite JSON strings, numbers, or booleans;
nested objects, arrays, and null are not supported. Omit for Goals whose schema accepts {}.
Create Goal Run › Responses
Goal Run durably accepted, or the current projection of an exact idempotent replay.
objectidPublic Goal Run identity. Persist this value and use it as goal_run_id when polling.
goal_idGoal identity supplied in the create path.
run_idInternal execution member exposed for correlation; do not use it in the Goal Run polling path.
Read-only identity and version of the exact RunSpec pinned by this Run.
statusStable telephone execution state. queued and in_progress are non-terminal; completed,
failed, and canceled are terminal. A completed call can still have result: null and
error: null briefly while CALL-E parses and saves the result.
Parsed result validated against the published result schema and durably persisted, or
null while processing or when the Run has an error. Its keys vary by Goal.
Unified execution or result-processing error, or null. Branch on code; keep message
for logs and operators. A non-null error is final and is mutually exclusive with result.
created_atUTC time at which CALL-E durably accepted this Goal Run.
completed_atUTC telephone-execution completion time, or null while execution is non-terminal.
Get Goal Run
Get an owner- and Goal-scoped Run and its structured result facts.
This is a pure read of the immutable execution snapshot. It does not resolve the current
Goal pointer, dispatch work, or start result materialization. Use the GoalRun.id returned
by create as goal_run_id; the nested telephone run_id is not valid in this path.
Poll until either result or error is non-null. A non-null result is the parsed object
validated against the published result schema. A non-null error means this Run will not
produce a result. status: completed with both fields null means result processing is still
in progress.
path Parameters
goal_idOpaque public Goal identity returned by CALL-E Chat publish success or GET /v1/goals.
Store it with your integration configuration. It identifies the reusable Goal and is
different from published_run_spec.id, goal_run_id, and the nested telephone run_id.
goal_run_idOpaque GoalRun.id returned by POST /v1/goals/{goal_id}/runs. Use it together with the
same goal_id when polling. Do not substitute the nested telephone run_id.
Get Goal Run › Responses
Current Goal Run execution and result state.
objectidPublic Goal Run identity. Persist this value and use it as goal_run_id when polling.
goal_idGoal identity supplied in the create path.
run_idInternal execution member exposed for correlation; do not use it in the Goal Run polling path.
Read-only identity and version of the exact RunSpec pinned by this Run.
statusStable telephone execution state. queued and in_progress are non-terminal; completed,
failed, and canceled are terminal. A completed call can still have result: null and
error: null briefly while CALL-E parses and saves the result.
Parsed result validated against the published result schema and durably persisted, or
null while processing or when the Run has an error. Its keys vary by Goal.
Unified execution or result-processing error, or null. Branch on code; keep message
for logs and operators. A non-null error is final and is mutually exclusive with result.
created_atUTC time at which CALL-E durably accepted this Goal Run.
completed_atUTC telephone-execution completion time, or null while execution is non-terminal.