Record outcome
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. 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
One step only. Complete the run with POST /signal/outcome/complete and the outcome's own agentKey (see OutcomeCompletionInput).
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 <= 255agentKey*stringThe step's agent key, matched exactly (case counts), up to 128 characters. It names its outcome too.
1 <= length <= 128runId*stringYour id for one workflow run. Every step of the run sends the same runId.
1 <= length <= 255usage*The LLM call to price. Required on credit, outcome and wallet signals.
composite?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 as sent. A value that is not an 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' \ -H 'Content-Type: application/json' \ -d '{ "customerId": "cmvgva5po000c07iir1vtn8vl", "agentKey": "support_ticket.triage", "runId": "TCK-48214", "usage": { "model": "claude-haiku-4-5", "inputTokens": 3200, "outputTokens": 800, "cacheTokens": 0, "cacheWriteTokens": 0 }}'{ "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.
OutcomeSignalInput
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. |
agentKey | string | yes | The step's agent key, matched exactly (case counts), up to 128 characters. It names its outcome too. |
runId | string | yes | Your id for one workflow run. Every step of the run sends the same runId. |
usage | SignalUsageBlock | yes | The LLM call to price. Required on credit, outcome and wallet signals. |
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 as sent. A value that is not an object is a 400. |
OutcomeSignalInput.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.
SignalUsageBlock
The LLM call to price. Required on credit, outcome and wallet signals.
| Field | Type | Required | Description |
|---|---|---|---|
model | string | yes | Models-page id, any case, e.g. gpt-4o. openai/gpt-4o is via AI/ML API. If archived, it waits as PENDING. |
inputTokens | integer | yes | Prompt tokens. |
outputTokens | integer | yes | Completion tokens. |
cacheTokens | integer | no | Tokens read from the prompt cache. Defaults to 0. |
cacheWriteTokens | integer | no | Tokens written to the prompt cache, priced at the cache-write rate. Defaults to 0. |
Record credit POST
Records one LLM call against a credit, named by `agentKey` (matched exactly, case included). The credit must be on the customer's plan, or covered by a composite on it. The price comes from the model's rates. Answers `202`; a signal that can't be counted stays `PENDING`. See [List raw signals](/docs/api-reference/signals/eventsListSignals).
Complete outcome POST
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`.