Complete outcome
Completes one run and bills its outcome once. Send the outcome's own agentKey (required) and the run's runId. When a composite on the plan covers it, the composite bills instead. Each call counts once, so send an idempotencyKey. Answers 202; a signal that can't be counted stays PENDING.
Base URL https://events.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
application/json- body
{ customerId | externalId, runId, agentKey }, plus member, idempotencyKey, and an optional composite and custom. A body with usage is a 400.
customerId?stringCustomer id, at most 128 characters. Required unless externalId is sent.
1 <= length <= 128externalId?stringYour own id for the customer, instead of customerId. An unknown id leaves the signal PENDING.
^[A-Za-z0-9-]{1,64}$1 <= length <= 64member?stringThe member's email, up to 254 characters. A new email adds the member; a non-email is a 400.
idempotencyKey?stringOne key is one signal: a repeat within 3 days, on any signal endpoint, returns the first signalId.
1 <= length <= 255runId*stringThe same runId the run's steps were sent with.
1 <= length <= 255agentKey*stringThe outcome's own agent key (not a step's), matched exactly (case counts), up to 128 characters.
1 <= length <= 128composite?Bills to a composite: { "<refId>": "<your id>" }, 128 characters each. { ref, value } is a 400.
custom?Free-form metadata up to 16 KB (UTF-8), kept with this completion. A non-object is a 400.
Accepted; counted after this answer. A repeated idempotencyKey gets the first signalId and replayed: true (details).
application/json- response
statusCode*integerThe HTTP status code of the answer, for example 200 or 202.
statusDetail*The status of the request and a short message.
result*The data of the answer.
curl -X POST 'https://events.clocknext.com/api/v1/signal/outcome/complete' \ -H 'Content-Type: application/json' \ -d '{ "customerId": "cmvgva5po000c07iir1vtn8vl", "agentKey": "support_ticket", "runId": "TCK-48214", "member": "priya.raman@northwindtraders.com", "idempotencyKey": "TCK-48214:complete"}'{ "statusCode": 202, "statusDetail": { "status": "SUCCESS", "message": "Signal accepted for processing." }, "result": { "queued": true, "signalId": "01a15a83-b894-770c-97b7-6bd2bd7b569e", "replayed": false }}Types
Every object type on this page, with its fields.
OutcomeCompletionInput
Name the customer with customerId or externalId: one is required. If both are sent, customerId wins and externalId is ignored. Unknown fields are dropped.
| Field | Type | Required | Description |
|---|---|---|---|
customerId | string | no | Customer id, at most 128 characters. Required unless externalId is sent. |
externalId | ExternalId | no | Your own id for the customer, instead of customerId. An unknown id leaves the signal PENDING. |
member | string | no | The member's email, up to 254 characters. A new email adds the member; a non-email is a 400. |
idempotencyKey | string | no | One key is one signal: a repeat within 3 days, on any signal endpoint, returns the first signalId. |
runId | string | yes | The same runId the run's steps were sent with. |
agentKey | string | yes | The outcome's own agent key (not a step's), matched exactly (case counts), up to 128 characters. |
composite | SignalCompositeBlock | no | Bills to a composite: { "<refId>": "<your id>" }, 128 characters each. { ref, value } is a 400. |
custom | object | no | Free-form metadata up to 16 KB (UTF-8), kept with this completion. A non-object is a 400. |
OutcomeCompletionInput.externalId
The id YOUR product uses for a customer: 1–64 letters, numbers or "-", matched exactly (case-sensitive). Unique among the organisation's active customers — an archived customer's id can be reused.
Record outcome POST
Records one step of a run: `agentKey` names the step, `runId` groups the steps. The outcome must be on the plan, or covered by a composite on it. A step bills nothing; bill the run with [Complete outcome](/docs/api-reference/signals/eventsCompleteOutcomeSignal). Answers `202`; a signal that can't be counted stays `PENDING`.
Record wallet POST
Charges one LLM call to the customer's wallet at the model's provider cost, with no margin and no rules. The plan must have a wallet; `agentKey` and `composite` are ignored. The wallet may go negative. Answers `202`; a signal that can't be counted stays `PENDING`.