Look Up Usage Logs by ID
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 returns. Ids that match nothing, or a PENDING signal, are in notFound.
Base URL https://events.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
ids*string1 to 10 distinct usage-log ids, separated by commas, sent once (?ids=a&ids=b is a 400). Repeated ids are removed. An id is matched without case. This is the only parameter: any other one is a 400.
The rows found, in the order of ids.
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/lookup?ids=0192a1ef-7c11-7a20-9b3d-4e5f6a7b8c9d%2C0192a1f0-3b2c-7d41-8e5f-6a7b8c9d0e12%2C0192a1f1-0a4d-7e52-9f60-7b8c9d0e1f23%2C0192a1f1-5c6e-7f63-8a71-8c9d0e1f2a34%2C0192a1f2-1d7f-7074-9b82-9d0e1f2a3b45%2C0192a1f2-8e90-7185-8c93-0e1f2a3b4c56'{ "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 } ], "notFound": [] }}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. |
List Customer Usage Log GET
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.
Record credit POST
Deprecated. Use [Record credit](/docs/api-reference/signals/eventsRecordCreditSignal) on `events.clocknext.com`; `@clocknext/sdk` 0.20 and later already do. Records one LLM call against a credit. The credit must be on the customer's plan, or covered by a composite on it. The price comes from the model's rates; you can't send one.