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
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
customerId?stringOur customer id. Send this or externalId; if both are sent, customerId wins. An archived customer is found.
externalId?stringYour own id for the customer (1–64 letters, numbers or "-", matched exactly), in place of customerId. Only an active customer is found.
^[A-Za-z0-9-]{1,64}$1 <= length <= 64limit?integerMaximum rows to return. Must be a positive number; clamped to 1–200.
1 <= value <= 20050cursor?stringOpaque 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?stringFirst 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.
dateto?stringLast day to include, YYYY-MM-DD (UTC). The whole day is included. Omit it for no end. Must not be before from.
dateA page of usage logs, newest first.
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 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'{ "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.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The signal id, in lower case. |
customerId | string | yes | The ClockNext id of the customer. A signal sent with externalId shows the customer's ClockNext id here. |
createdAt | string | yes | When the API received the signal. |
member | string | null | yes | The member's name, or its email when it has no name. null when the signal named no member. |
entitlement | object | yes | What this row is for. |
status | "SUCCESS" | yes | Always SUCCESS: only counted signals are rows. |
llm | UsageLogLlm | yes | The model call of a CREDIT, OUTCOME or WALLET row; null on the others. |
credit | object | null | yes | Set only on a CREDIT row. |
outcome | UsageLogOutcomeAttribution | null | yes | Set only on an OUTCOME row (one step of a run). |
outcomeCompletion | object | null | yes | Only on OUTCOME_COMPLETION. outcomeUsed is 1, or 0 when a composite covers the run. |
composite | object | null | yes | Only on COMPOSITE. refId is the composite key, value the composite value you sent. |
unit | object | null | yes | Set only on a UNIT row. customerCost is the price of these units on your plan's tiers. |
wallet | object | null | yes | What each wallet paid, in USD; amount is fromMainWallet + fromReservedWallet. |
coveredByComposite | object | null | yes | The composite charged for this row instead (its key and value). null when the row is charged by itself. |
custom | object | null | yes | The custom object sent with this signal, as sent. null when none was sent. |
UsageLogEntry.entitlement
What this row is for.
| Field | Type | Required | Description |
|---|---|---|---|
type | "CREDIT" | "OUTCOME" | "OUTCOME_COMPLETION" | "UNIT" | "COMPOSITE" | "WALLET" | yes | OUTCOME: a step of a run. OUTCOME_COMPLETION: a run completed. COMPOSITE: a composite completed. |
id | string | null | yes | The credit, outcome, unit or composite id. null on a WALLET row. |
name | string | null | yes | The name of the credit, outcome, unit or composite. null on a WALLET row. |
agentKey | string | null | yes | The agentKey sent (the step's key on an OUTCOME row). null on COMPOSITE and WALLET rows. |
billingMode | "ADVANCE" | "ARREAR" | null | yes | ADVANCE: taken from the prepaid balance. ARREAR: billed at the cycle end. null on a WALLET row. |
useWalletForArrear | boolean | yes | True when the row took money from a wallet (a WALLET row, or ARREAR on a wallet-funded plan). |
UsageLogEntry.llm
| Field | Type | Required | Description |
|---|---|---|---|
model | object | yes | The model's name in your workspace (or the model id) and its provider. |
usage | UsageLogUsage | yes | The token counts of the model call. |
cost | object | yes | The cost of the model call, in USD. |
UsageLogEntry.llm.model
The model's name in your workspace (or the model id) and its provider.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | null | yes | The model's name in your workspace, or the model id. null when the model is not known. |
provider | string | null | yes | The model's provider, for example OpenAI. null when the provider is not known. |
UsageLogUsage
| Field | Type | Required | Description |
|---|---|---|---|
inputTokens | integer | yes | Input (prompt) tokens of the model call. |
outputTokens | integer | yes | Output (completion) tokens of the model call. |
cacheTokens | integer | yes | Cache-read tokens. |
cacheWriteTokens | integer | yes | Cache-write tokens. |
UsageLogEntry.llm.cost
The cost of the model call, in USD.
| Field | Type | Required | Description |
|---|---|---|---|
providerCost | number | yes | USD. |
customerCost | number | yes | USD. |
UsageLogEntry.credit
| Field | Type | Required | Description |
|---|---|---|---|
creditsUsed | number | yes | Credits taken from the plan. |
customerCost | number | yes | USD: the credits at your price. |
appliedRules | UsageLogAppliedRule[] | yes | The credit rules that set the charge of this row. Empty when no rule matched. |
UsageLogAppliedRule
| Field | Type | Required | Description |
|---|---|---|---|
ruleId | string | null | no | The credit rule that matched. null when that rule was deleted later. |
ruleName | string | yes | The rule's name when it matched. It stays the same when the rule is renamed or deleted. |
mode | "MARGIN" | "CREDIT" | null | yes | MARGIN: another margin on the model cost. CREDIT: a fixed number of credits. null on older rows. |
marginPercentApplied | number | null | yes | The margin a MARGIN rule applied; null for a CREDIT rule. |
creditsApplied | number | yes | The credits this rule set. |
UsageLogOutcomeAttribution
| Field | Type | Required | Description |
|---|---|---|---|
stepNumber | integer | null | yes | The step's position in the outcome. A step may repeat within a run. |
stepName | string | null | yes | The name of the outcome step this signal performed. null when the step has no name. |
runId | string | null | yes | Your run id. Every step of one run has it. |
closedRun | boolean | yes | True when the run has a completion. |
customerCost | number | yes | Always 0: the run is charged at its completion. |
UsageLogEntry.outcomeCompletion
| Field | Type | Required | Description |
|---|---|---|---|
runId | string | null | yes | Your run id, sent with the run's signals. null when the completion has no run id. |
outcomeUsed | number | yes | Outcomes taken from the plan: 1, or 0 when a composite covers the run. |
customerCost | number | yes | The outcome's price on your plan, in USD. 0 when a composite covers the run. |
UsageLogEntry.composite
| Field | Type | Required | Description |
|---|---|---|---|
refId | string | yes | The composite key. |
value | string | yes | The composite value you sent for this composite occurrence. |
compositeUsed | number | yes | Composite occurrences taken from the plan. Always 1. |
customerCost | number | yes | The composite's price on your plan, in USD. |
UsageLogEntry.unit
| Field | Type | Required | Description |
|---|---|---|---|
unitsUsed | number | yes | Units taken from the plan. 0 when a composite covers the row. |
customerCost | number | yes | The price of these units on your plan's tiers, in USD. 0 when a composite covers the row. |
UsageLogEntry.wallet
| Field | Type | Required | Description |
|---|---|---|---|
fromMainWallet | number | yes | What the main wallet paid, in USD. |
fromReservedWallet | number | yes | What the Reserved Wallet paid, in USD. |
amount | number | yes | What the wallets paid in total, in USD. It is fromMainWallet + fromReservedWallet. |
UsageLogEntry.coveredByComposite
| Field | Type | Required | Description |
|---|---|---|---|
refId | string | yes | The composite key of the composite that is charged for this row. |
value | string | yes | The 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`.