Record credit
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.
Base URL https://events.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
application/json- body
Name the customer with customerId or externalId: one is required. If both are sent, customerId wins and externalId is ignored. Unknown fields are dropped.
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 credit's own agent key, matched exactly (case counts). At most 128 characters.
1 <= length <= 128usage*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?Any JSON object up to 16 KB (UTF-8), stored with the signal. Credit rules can match on its keys.
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/credit' \ -H 'Content-Type: application/json' \ -d '{ "customerId": "cmvgva5po000c07iir1vtn8vl", "agentKey": "chat_message", "member": "daniel.okafor@northwindtraders.com", "usage": { "model": "gpt-4o-mini", "inputTokens": 1876, "outputTokens": 883, "cacheTokens": 204, "cacheWriteTokens": 0 }, "idempotencyKey": "chat:nw:req_1005"}'{ "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.
CreditSignalInput
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 credit's own agent key, matched exactly (case counts). At most 128 characters. |
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 | Any JSON object up to 16 KB (UTF-8), stored with the signal. Credit rules can match on its keys. |
CreditSignalInput.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. |
Webhooks
How webhook events reach your server — the request, verifying the signature, responding, retries and duplicates.
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`.