Record unit
Records quantity units (default 1) against a unit, named by agentKey (case counts). The unit must be on the plan, or covered by a composite on it. An ADVANCE unit can go below 0. 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
No usage block: a unit has no model and no tokens. One call is one report of quantity units, 1 when left out.
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 unit's agent key, matched exactly (case counts). At most 128 characters.
1 <= length <= 128quantity?integerHow many units, 1 to 1,000,000. Defaults to 1.
1 <= value <= 10000001composite?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 and shown in the usage log.
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/unit' \ -H 'Content-Type: application/json' \ -d '{ "customerId": "cmvgva5po000c07iir1vtn8vl", "agentKey": "pdf_export", "member": "daniel.okafor@northwindtraders.com"}'{ "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.
UnitSignalInput
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 unit's agent key, matched exactly (case counts). At most 128 characters. |
quantity | integer | no | How many units, 1 to 1,000,000. Defaults to 1. |
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 and shown in the usage log. |
UnitSignalInput.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 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`.
Complete composite POST
Completes one composite occurrence and bills it once. In `composite`, the key is its `refId` and the value is your occurrence id. Signals that carry this value are billed by the composite. Each call counts once, so send an `idempotencyKey`. Answers `202`; a signal that can't be counted stays `PENDING`.