ClocknextClocknextHelp
DocumentationAPI ReferenceMCP Tools
Dashboard

Get started

OverviewQuickstart

Good to know

Response formatHandling errorsPaginating resultsSending data reliablyYour own customer idsWebhooks

API reference

Signals

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POSTList Customer Usage Log GETLook Up Usage Logs by ID GET

Deprecated

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POST

Customers

List customers GETCreate a customer POSTGet a customer GETUpdate a customer PATCHDelete a customer DELETEGet a customer's balances GETGet a customer's wallet ledger GETSet a customer's low-balance alert for wallet PUTGet a customer's current plan GETChange a recurring grant PUTUpdate a customer's card POSTGet a customer's invoice balance GETAdjust a customer's invoice balance POST

Deprecated

List Customer Usage Log GETLook Up Usage Logs by ID GET

Manage

Manage a customer's credit balance POSTManage a customer's outcome balance POSTManage a customer's unit balance POSTManage a customer's composite balance POSTManage a customer's wallet balance POST

Members

List a customer's members GETAdd a member POSTUpdate a member PATCHRemove a member DELETE

Plans and Entitlements

PlansPackagesCreditsOutcomesUnitsComposites

Taxes

List taxes GETCreate a tax POSTGet a tax GETUpdate a tax PATCH

Purchases

List purchases GETCreate a purchase POSTGet a purchase GETUpdate a purchase's auto-payment setting PATCHCancel a purchase POST

Checkout

Create a checkout POST

Subscriptions

List subscriptions GETGet a subscription GETCancel a subscription POSTAdd packages to a subscription POSTRemove a package from a subscription POST

Plan changes

List plan changes GETPreview a plan change POSTChange a customer's plan POSTGet a plan change GET

Invoices

List invoices GETGet an invoice GETMint a hosted pay link GETRecord a payment POST

Credit notes

List credit notes GETCreate a credit note POSTGet a credit note GETVoid a credit note POST

Refunds

List refunds GETRefund to the card POSTGet a refund GET

Payments

List payments GETGet a payment GET

Webhooks

Customer Portal

Mint a customer-portal access token POST

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

POST
/signal/outcome

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Request Body

application/json
  1. body
  1. body
  2. …

One step only. Complete the run with POST /signal/outcome/complete and the outcome's own agentKey (see OutcomeCompletionInput).

customerId?string

Customer id, at most 128 characters. Required unless externalId is sent.

Length1 <= length <= 128
externalId?string

Your own id for the customer, instead of customerId. An unknown id leaves the signal PENDING.

Match^[A-Za-z0-9-]{1,64}$
Length1 <= length <= 64
member?string

The member's email, up to 254 characters. A new email adds the member; a non-email is a 400.

idempotencyKey?string

One key is one signal: a repeat within 3 days, on any signal endpoint, returns the first signalId.

Length1 <= length <= 255
agentKey*string

The step's agent key, matched exactly (case counts), up to 128 characters. It names its outcome too.

Length1 <= length <= 128
runId*string

Your id for one workflow run. Every step of the run sends the same runId.

Length1 <= length <= 255
usage*

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.

Response Body

Accepted; counted after this answer. A repeated idempotencyKey gets the first signalId and replayed: true (details).

application/json
  1. response
  1. response
  2. …
statusCode*integer

The 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  }}'
Example Response
{  "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.

FieldTypeRequiredDescription
customerIdstringnoCustomer id, at most 128 characters. Required unless externalId is sent.
externalIdExternalIdnoYour own id for the customer, instead of customerId. An unknown id leaves the signal PENDING.
memberstringnoThe member's email, up to 254 characters. A new email adds the member; a non-email is a 400.
idempotencyKeystringnoOne key is one signal: a repeat within 3 days, on any signal endpoint, returns the first signalId.
agentKeystringyesThe step's agent key, matched exactly (case counts), up to 128 characters. It names its outcome too.
runIdstringyesYour id for one workflow run. Every step of the run sends the same runId.
usageSignalUsageBlockyesThe LLM call to price. Required on credit, outcome and wallet signals.
compositeSignalCompositeBlocknoBills to a composite: { "<refId>": "<your id>" }, 128 characters each. { ref, value } is a 400.
customobjectnoFree-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.

FieldTypeRequiredDescription
modelstringyesModels-page id, any case, e.g. gpt-4o. openai/gpt-4o is via AI/ML API. If archived, it waits as PENDING.
inputTokensintegeryesPrompt tokens.
outputTokensintegeryesCompletion tokens.
cacheTokensintegernoTokens read from the prompt cache. Defaults to 0.
cacheWriteTokensintegernoTokens 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`.