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

List Customer Usage Log

One customer's counted signals in one feed, newest first: credit, outcome steps and completions, unit, wallet and composite. Name the customer with customerId or externalId. Paged with limit and cursor, for the last 30 days unless you send from or to. A row a composite covers shows 0.

Base URL https://events.clocknext.com/api/v1

GET
/signal/usage-log

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Query Parameters

customerId?string

Our customer id. Send this or externalId; if both are sent, customerId wins. An archived customer is found.

externalId?string

Your own id for the customer (1–64 letters, numbers or "-", matched exactly), in place of customerId. Only an active customer is found.

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

Maximum rows to return. Must be a positive number; clamped to 1–200.

Range1 <= value <= 200
Default50
cursor?string

Opaque token from a previous response's nextCursor. Omit it for the first page. It keeps the first page's days, so the next pages read the same days however late you ask.

from?string

First day to include, YYYY-MM-DD (UTC). The whole day is included. Omit it to start 30 days before the end of to, or 30 days before now.

Formatdate
to?string

Last day to include, YYYY-MM-DD (UTC). The whole day is included. Omit it for no end. Must not be before from.

Formatdate

Response Body

A page of usage logs, newest first.

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.

Example Request
curl -X GET 'https://events.clocknext.com/api/v1/signal/usage-log?customerId=cus_abc123&limit=25&cursor=eyJ0cyI6IjIwMjYtMTAtMDdUMTM6MDA6NTEuMDIzWiIsImlkIjoiMDE5MmExZWYtN2MxMS03YTIwLTliM2QtNGU1ZjZhN2I4YzlkIiwiZnJvbSI6IjIwMjYtMDktMDdUMDA6MDA6MDAuMDAwWiJ9&from=2026-10-01&to=2026-10-07'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "usageLogs": [      {        "id": "01a15a16-01d4-761e-baec-dbe7f088c96c",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:34.132Z",        "member": null,        "entitlement": {          "type": "UNIT",          "id": "cmvgv92mk000n08l5jjjxnnul",          "name": "PDF Export",          "agentKey": "pdf_export",          "billingMode": "ADVANCE",          "useWalletForArrear": false        },        "status": "SUCCESS",        "llm": null,        "credit": null,        "outcome": null,        "outcomeCompletion": null,        "composite": null,        "unit": {          "unitsUsed": 1,          "customerCost": 0.25        },        "wallet": null,        "coveredByComposite": null,        "custom": null      },      {        "id": "01a15a15-ff39-734c-957c-d0387537a318",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:33.465Z",        "member": "Priya Raman",        "entitlement": {          "type": "CREDIT",          "id": "cmvgvfd63000508l2oexbgpzs",          "name": "Chat Message",          "agentKey": "chat_message",          "billingMode": "ADVANCE",          "useWalletForArrear": false        },        "status": "SUCCESS",        "llm": {          "model": {            "name": "GPT-4o mini",            "provider": "OpenAI"          },          "usage": {            "inputTokens": 2000,            "outputTokens": 500,            "cacheTokens": 0,            "cacheWriteTokens": 0          },          "cost": {            "providerCost": 0.0006,            "customerCost": 0.00084          }        },        "credit": {          "creditsUsed": 0.701754386,          "customerCost": 0.00084,          "appliedRules": []        },        "outcome": null,        "outcomeCompletion": null,        "composite": null,        "unit": null,        "wallet": null,        "coveredByComposite": null,        "custom": null      },      {        "id": "01a15a15-d708-7784-a954-24cad1d90e00",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:23.176Z",        "member": null,        "entitlement": {          "type": "OUTCOME_COMPLETION",          "id": "cmvgvffng000808l237059in9",          "name": "Resolved Support Ticket",          "agentKey": "support_ticket",          "billingMode": "ADVANCE",          "useWalletForArrear": false        },        "status": "SUCCESS",        "llm": null,        "credit": null,        "outcome": null,        "outcomeCompletion": {          "runId": "TCK-48299",          "outcomeUsed": 1,          "customerCost": 0.126023        },        "composite": null,        "unit": null,        "wallet": null,        "coveredByComposite": null,        "custom": null      },      {        "id": "01a15a15-b99a-74d4-b23a-f7835bce0aff",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:15.642Z",        "member": null,        "entitlement": {          "type": "WALLET",          "id": null,          "name": null,          "agentKey": null,          "billingMode": null,          "useWalletForArrear": true        },        "status": "SUCCESS",        "llm": {          "model": {            "name": "Claude Sonnet 4.5 (latest)",            "provider": "Anthropic"          },          "usage": {            "inputTokens": 12000,            "outputTokens": 3000,            "cacheTokens": 2000,            "cacheWriteTokens": 500          },          "cost": {            "providerCost": 0.083475,            "customerCost": 0.083475          }        },        "credit": null,        "outcome": null,        "outcomeCompletion": null,        "composite": null,        "unit": null,        "wallet": {          "fromMainWallet": 0.083475,          "fromReservedWallet": 0,          "amount": 0.083475        },        "coveredByComposite": null,        "custom": null      },      {        "id": "01a15a15-b773-70e3-ad71-87994218bda2",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:15.091Z",        "member": null,        "entitlement": {          "type": "COMPOSITE",          "id": "cmvgvfh1e000i08l2oi7oozop",          "name": "Research Report",          "agentKey": null,          "billingMode": "ARREAR",          "useWalletForArrear": true        },        "status": "SUCCESS",        "llm": null,        "credit": null,        "outcome": null,        "outcomeCompletion": null,        "composite": {          "refId": "research_report",          "value": "RPT-2026-Q4-EV",          "compositeUsed": 1,          "customerCost": 12        },        "unit": null,        "wallet": {          "fromMainWallet": 12,          "fromReservedWallet": 0,          "amount": 12        },        "coveredByComposite": null,        "custom": null      },      {        "id": "01a15a15-b661-71b3-a4cd-5a3db200a258",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:14.817Z",        "member": null,        "entitlement": {          "type": "UNIT",          "id": "cmvgv92mk000n08l5jjjxnnul",          "name": "PDF Export",          "agentKey": "pdf_export",          "billingMode": "ADVANCE",          "useWalletForArrear": false        },        "status": "SUCCESS",        "llm": null,        "credit": null,        "outcome": null,        "outcomeCompletion": null,        "composite": null,        "unit": {          "unitsUsed": 0,          "customerCost": 0        },        "wallet": null,        "coveredByComposite": {          "refId": "research_report",          "value": "RPT-2026-Q4-EV"        },        "custom": null      },      {        "id": "01a15a15-b553-7618-aa36-e48aa477b055",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:14.547Z",        "member": null,        "entitlement": {          "type": "OUTCOME_COMPLETION",          "id": "cmvgvffxr000c08l28wch48fa",          "name": "Contract Review",          "agentKey": "contract_review",          "billingMode": "ARREAR",          "useWalletForArrear": false        },        "status": "SUCCESS",        "llm": null,        "credit": null,        "outcome": null,        "outcomeCompletion": {          "runId": "RPT-2026-Q4-EV-legal",          "outcomeUsed": 0,          "customerCost": 0        },        "composite": null,        "unit": null,        "wallet": null,        "coveredByComposite": {          "refId": "research_report",          "value": "RPT-2026-Q4-EV"        },        "custom": null      },      {        "id": "01a15a15-b446-7489-93a0-25a7a23108d5",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:14.278Z",        "member": null,        "entitlement": {          "type": "OUTCOME",          "id": "cmvgvffxr000c08l28wch48fa",          "name": "Contract Review",          "agentKey": "contract_review.extract",          "billingMode": "ARREAR",          "useWalletForArrear": false        },        "status": "SUCCESS",        "llm": {          "model": {            "name": "Claude Sonnet 4.5 (latest)",            "provider": "Anthropic"          },          "usage": {            "inputTokens": 20000,            "outputTokens": 5000,            "cacheTokens": 0,            "cacheWriteTokens": 0          },          "cost": {            "providerCost": 0.135,            "customerCost": 0.135          }        },        "credit": null,        "outcome": {          "stepNumber": 1,          "stepName": "Extract clauses",          "runId": "RPT-2026-Q4-EV-legal",          "closedRun": true,          "customerCost": 0        },        "outcomeCompletion": null,        "composite": null,        "unit": null,        "wallet": null,        "coveredByComposite": {          "refId": "research_report",          "value": "RPT-2026-Q4-EV"        },        "custom": null      },      {        "id": "01a15a15-b333-70c1-b65d-b3adbfb52363",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:14.003Z",        "member": null,        "entitlement": {          "type": "CREDIT",          "id": "cmvgvfdfz000608l2wsff83hq",          "name": "Deep Research",          "agentKey": "deep_research",          "billingMode": "ADVANCE",          "useWalletForArrear": false        },        "status": "SUCCESS",        "llm": {          "model": {            "name": "Claude Sonnet 4.5 (latest)",            "provider": "Anthropic"          },          "usage": {            "inputTokens": 52000,            "outputTokens": 21000,            "cacheTokens": 3000,            "cacheWriteTokens": 0          },          "cost": {            "providerCost": 0.4719,            "customerCost": 0.589875          }        },        "credit": {          "creditsUsed": 0,          "customerCost": 0,          "appliedRules": []        },        "outcome": null,        "outcomeCompletion": null,        "composite": null,        "unit": null,        "wallet": null,        "coveredByComposite": {          "refId": "research_report",          "value": "RPT-2026-Q4-EV"        },        "custom": null      },      {        "id": "01a15a15-b21e-71fe-961a-fa02b8c13f4d",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:13.726Z",        "member": null,        "entitlement": {          "type": "COMPOSITE",          "id": "cmvgvfgqe000f08l219wzyt7v",          "name": "Voice AI Call",          "agentKey": null,          "billingMode": "ADVANCE",          "useWalletForArrear": false        },        "status": "SUCCESS",        "llm": null,        "credit": null,        "outcome": null,        "outcomeCompletion": null,        "composite": {          "refId": "voice_call",          "value": "CALL-7f3a91",          "compositeUsed": 1,          "customerCost": 1.75        },        "unit": null,        "wallet": null,        "coveredByComposite": null,        "custom": null      },      {        "id": "01a15a15-aeea-7230-b0a2-e441dcec307a",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:12.906Z",        "member": null,        "entitlement": {          "type": "UNIT",          "id": "cmvgv92vf000o08l5qnqm39eo",          "name": "Voice Minute",          "agentKey": "voice_minute",          "billingMode": "ARREAR",          "useWalletForArrear": true        },        "status": "SUCCESS",        "llm": null,        "credit": null,        "outcome": null,        "outcomeCompletion": null,        "composite": null,        "unit": {          "unitsUsed": 7,          "customerCost": 0.42        },        "wallet": {          "fromMainWallet": 0.42,          "fromReservedWallet": 0,          "amount": 0.42        },        "coveredByComposite": null,        "custom": null      },      {        "id": "01a15a15-a98b-76c1-ab39-7f9c96b4e768",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:11.531Z",        "member": null,        "entitlement": {          "type": "OUTCOME_COMPLETION",          "id": "cmvgvffxr000c08l28wch48fa",          "name": "Contract Review",          "agentKey": "contract_review",          "billingMode": "ARREAR",          "useWalletForArrear": true        },        "status": "SUCCESS",        "llm": null,        "credit": null,        "outcome": null,        "outcomeCompletion": {          "runId": "MSA-2026-114",          "outcomeUsed": 1,          "customerCost": 0.9316        },        "composite": null,        "unit": null,        "wallet": {          "fromMainWallet": 0.9316,          "fromReservedWallet": 0,          "amount": 0.9316        },        "coveredByComposite": null,        "custom": null      },      {        "id": "01a15a15-a87b-7771-a60e-b22ba5cae77f",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:11.259Z",        "member": null,        "entitlement": {          "type": "OUTCOME",          "id": "cmvgvffxr000c08l28wch48fa",          "name": "Contract Review",          "agentKey": "contract_review.risk",          "billingMode": "ARREAR",          "useWalletForArrear": false        },        "status": "SUCCESS",        "llm": {          "model": {            "name": "Claude Haiku 4.5 (latest)",            "provider": "Anthropic"          },          "usage": {            "inputTokens": 5000,            "outputTokens": 1000,            "cacheTokens": 0,            "cacheWriteTokens": 0          },          "cost": {            "providerCost": 0.01,            "customerCost": 0.01          }        },        "credit": null,        "outcome": {          "stepNumber": 3,          "stepName": "Risk score",          "runId": "MSA-2026-114",          "closedRun": true,          "customerCost": 0        },        "outcomeCompletion": null,        "composite": null,        "unit": null,        "wallet": null,        "coveredByComposite": null,        "custom": null      },      {        "id": "01a15a15-9ba8-7113-8fd5-66e22bdd5a4b",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "createdAt": "2026-10-20T16:12:07.976Z",        "member": "Daniel Okafor (Ops)",        "entitlement": {          "type": "CREDIT",          "id": "cmvgvfdp2000708l2vd8r110d",          "name": "Code Review",          "agentKey": "code_review",          "billingMode": "ARREAR",          "useWalletForArrear": true        },        "status": "SUCCESS",        "llm": {          "model": {            "name": "GPT-4o",            "provider": "OpenAI"          },          "usage": {            "inputTokens": 19000,            "outputTokens": 4800,            "cacheTokens": 1200,            "cacheWriteTokens": 0          },          "cost": {            "providerCost": 0.097,            "customerCost": 0.13095          }        },        "credit": {          "creditsUsed": 0.8997101449,          "customerCost": 0.13095,          "appliedRules": []        },        "outcome": null,        "outcomeCompletion": null,        "composite": null,        "unit": null,        "wallet": {          "fromMainWallet": 0.13095,          "fromReservedWallet": 0,          "amount": 0.13095        },        "coveredByComposite": null,        "custom": null      }    ],    "nextCursor": null  }}

Types

Every object type on this page, with its fields.

UsageLogEntry

One counted signal, as the usage log and the lookup return it. Only the group of entitlement.type is set; the others are null. Money is USD, 6 decimals. A row a composite covers shows 0.

FieldTypeRequiredDescription
idstringyesThe signal id, in lower case.
customerIdstringyesThe ClockNext id of the customer. A signal sent with externalId shows the customer's ClockNext id here.
createdAtstringyesWhen the API received the signal.
memberstring | nullyesThe member's name, or its email when it has no name. null when the signal named no member.
entitlementobjectyesWhat this row is for.
status"SUCCESS"yesAlways SUCCESS: only counted signals are rows.
llmUsageLogLlmyesThe model call of a CREDIT, OUTCOME or WALLET row; null on the others.
creditobject | nullyesSet only on a CREDIT row.
outcomeUsageLogOutcomeAttribution | nullyesSet only on an OUTCOME row (one step of a run).
outcomeCompletionobject | nullyesOnly on OUTCOME_COMPLETION. outcomeUsed is 1, or 0 when a composite covers the run.
compositeobject | nullyesOnly on COMPOSITE. refId is the composite key, value the composite value you sent.
unitobject | nullyesSet only on a UNIT row. customerCost is the price of these units on your plan's tiers.
walletobject | nullyesWhat each wallet paid, in USD; amount is fromMainWallet + fromReservedWallet.
coveredByCompositeobject | nullyesThe composite charged for this row instead (its key and value). null when the row is charged by itself.
customobject | nullyesThe custom object sent with this signal, as sent. null when none was sent.

UsageLogEntry.entitlement

What this row is for.

FieldTypeRequiredDescription
type"CREDIT" | "OUTCOME" | "OUTCOME_COMPLETION" | "UNIT" | "COMPOSITE" | "WALLET"yesOUTCOME: a step of a run. OUTCOME_COMPLETION: a run completed. COMPOSITE: a composite completed.
idstring | nullyesThe credit, outcome, unit or composite id. null on a WALLET row.
namestring | nullyesThe name of the credit, outcome, unit or composite. null on a WALLET row.
agentKeystring | nullyesThe agentKey sent (the step's key on an OUTCOME row). null on COMPOSITE and WALLET rows.
billingMode"ADVANCE" | "ARREAR" | nullyesADVANCE: taken from the prepaid balance. ARREAR: billed at the cycle end. null on a WALLET row.
useWalletForArrearbooleanyesTrue when the row took money from a wallet (a WALLET row, or ARREAR on a wallet-funded plan).

UsageLogEntry.llm

FieldTypeRequiredDescription
modelobjectyesThe model's name in your workspace (or the model id) and its provider.
usageUsageLogUsageyesThe token counts of the model call.
costobjectyesThe cost of the model call, in USD.

UsageLogEntry.llm.model

The model's name in your workspace (or the model id) and its provider.

FieldTypeRequiredDescription
namestring | nullyesThe model's name in your workspace, or the model id. null when the model is not known.
providerstring | nullyesThe model's provider, for example OpenAI. null when the provider is not known.

UsageLogUsage

FieldTypeRequiredDescription
inputTokensintegeryesInput (prompt) tokens of the model call.
outputTokensintegeryesOutput (completion) tokens of the model call.
cacheTokensintegeryesCache-read tokens.
cacheWriteTokensintegeryesCache-write tokens.

UsageLogEntry.llm.cost

The cost of the model call, in USD.

FieldTypeRequiredDescription
providerCostnumberyesUSD.
customerCostnumberyesUSD.

UsageLogEntry.credit

FieldTypeRequiredDescription
creditsUsednumberyesCredits taken from the plan.
customerCostnumberyesUSD: the credits at your price.
appliedRulesUsageLogAppliedRule[]yesThe credit rules that set the charge of this row. Empty when no rule matched.

UsageLogAppliedRule

FieldTypeRequiredDescription
ruleIdstring | nullnoThe credit rule that matched. null when that rule was deleted later.
ruleNamestringyesThe rule's name when it matched. It stays the same when the rule is renamed or deleted.
mode"MARGIN" | "CREDIT" | nullyesMARGIN: another margin on the model cost. CREDIT: a fixed number of credits. null on older rows.
marginPercentAppliednumber | nullyesThe margin a MARGIN rule applied; null for a CREDIT rule.
creditsAppliednumberyesThe credits this rule set.

UsageLogOutcomeAttribution

FieldTypeRequiredDescription
stepNumberinteger | nullyesThe step's position in the outcome. A step may repeat within a run.
stepNamestring | nullyesThe name of the outcome step this signal performed. null when the step has no name.
runIdstring | nullyesYour run id. Every step of one run has it.
closedRunbooleanyesTrue when the run has a completion.
customerCostnumberyesAlways 0: the run is charged at its completion.

UsageLogEntry.outcomeCompletion

FieldTypeRequiredDescription
runIdstring | nullyesYour run id, sent with the run's signals. null when the completion has no run id.
outcomeUsednumberyesOutcomes taken from the plan: 1, or 0 when a composite covers the run.
customerCostnumberyesThe outcome's price on your plan, in USD. 0 when a composite covers the run.

UsageLogEntry.composite

FieldTypeRequiredDescription
refIdstringyesThe composite key.
valuestringyesThe composite value you sent for this composite occurrence.
compositeUsednumberyesComposite occurrences taken from the plan. Always 1.
customerCostnumberyesThe composite's price on your plan, in USD.

UsageLogEntry.unit

FieldTypeRequiredDescription
unitsUsednumberyesUnits taken from the plan. 0 when a composite covers the row.
customerCostnumberyesThe price of these units on your plan's tiers, in USD. 0 when a composite covers the row.

UsageLogEntry.wallet

FieldTypeRequiredDescription
fromMainWalletnumberyesWhat the main wallet paid, in USD.
fromReservedWalletnumberyesWhat the Reserved Wallet paid, in USD.
amountnumberyesWhat the wallets paid in total, in USD. It is fromMainWallet + fromReservedWallet.

UsageLogEntry.coveredByComposite

FieldTypeRequiredDescription
refIdstringyesThe composite key of the composite that is charged for this row.
valuestringyesThe composite value you sent for that composite occurrence.

Retry signals POST

Sends 1 to 50 `PENDING` signals through processing again, for example after you created the missing customer. Answers `202` at once; see the result in [List raw signals](/docs/api-reference/signals/eventsListSignals). A signal gets 11 attempts, then becomes `REJECTED`. A retry never counts a signal twice.

Look Up Usage Logs by ID GET

Up to 10 usage-log rows by id (the signal id), from any customer of your organization, in the order of `ids`. Each row is the one [List Customer Usage Log](/docs/api-reference/signals/eventsListUsageLog) returns. Ids that match nothing, or a `PENDING` signal, are in `notFound`.