ClocknextHelp
DocumentationAPI ReferenceMCP Tools
Dashboard

Get started

OverviewQuickstart

Good to know

Response formatHandling errorsPaginating resultsSending data reliablyYour own customer idsWebhooks

API reference

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POST
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 PUTGet a customer's current plan GETChange a recurring grant PUTList Customer Usage Log GETLook Up Usage Logs by ID GET
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
List a customer's members GETAdd a member POSTUpdate a member PATCHRemove a member DELETE
PlansCreditsOutcomesUnitsComposites
List taxes GETCreate a tax POSTGet a tax GETUpdate a tax PATCH
List purchases GETCreate a purchase POSTGet a purchase GETUpdate a purchase's auto-payment setting PATCHCancel a purchase POST
List invoices GETGet an invoice GETMint a hosted pay link GET
List payments GETGet a payment GET
wallet.balance.update POSTwallet.balance.drop POST
Mint a customer-portal access token POST
Customers

Look Up Usage Logs by ID

Up to 10 usage-log rows by id, in one call — for example the usageLogId of each USAGE_LOG row in a customer's wallet ledger. Scoped to your organization, not to one customer: every row has its own customerId. Rows come back in the order of ids; duplicate ids are removed. Ids that match nothing in your organization are listed in notFound. The row format is not the same as GET /signal/usage-log: see UsageLogLookupEntry.

GET
/signal/usage-log/lookup

Authorization

apiKey
AuthorizationBearer <token>

Organisation-scoped key from Settings → API Keys.

In: header

Query Parameters

ids*string

1 to 10 distinct usage-log ids, separated by commas, sent once (?ids=a&ids=b is a 400). Duplicates are removed. This is the only parameter: any other one is a 400.

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/signal/usage-log/lookup?ids=cmgl5a1b20001x7k3p9m2q4w%2Ccmgl5adhe0007d9x5b1y5c7d"
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "usageLogs": [      {        "id": "cmgl5a3c40002y9m5r1n4s6x",        "customerId": "cmgk1qz8a0001v3c9h2e5d7k",        "createdAt": "2026-10-12T10:01:00.000Z",        "status": "SUCCESS",        "entitlement": {          "type": "credit",          "id": "cmgk1r0b20004p8m3x6w1n9s",          "name": "AI Credits"        },        "member": "Ichigo Kurosaki",        "model": {          "name": "gpt-4o",          "provider": "OpenAI"        },        "usage": {          "inputTokens": 900,          "outputTokens": 150,          "cacheTokens": 0,          "cacheWriteTokens": 0        },        "cost": {          "providedCost": "$0.003800",          "customerCost": "$0.00"        },        "credit": {          "amount": "8",          "appliedRules": []        },        "outcome": null,        "outcomeCompletion": null,        "unit": null,        "compositeCompletion": null,        "wallet": null,        "composite": {          "id": "cmgk1r6e8000dz9q4m7b2x5h",          "refId": "session_id",          "runId": "onb_123"        },        "custom": null      },      {        "id": "cmgl5adhe0007d9x5b1y5c7d",        "customerId": "cmgk1qz8a0001v3c9h2e5d7k",        "createdAt": "2026-10-12T10:05:00.000Z",        "status": "SUCCESS",        "entitlement": {          "type": "composite_completion",          "id": "cmgk1r6e8000dz9q4m7b2x5h",          "name": "Onboarding Flow"        },        "member": null,        "model": null,        "usage": {          "inputTokens": 0,          "outputTokens": 0,          "cacheTokens": 0,          "cacheWriteTokens": 0        },        "cost": {          "providedCost": "$0.00",          "customerCost": "$2.00"        },        "credit": null,        "outcome": null,        "outcomeCompletion": null,        "unit": null,        "compositeCompletion": {          "refId": "session_id",          "runId": "onb_123",          "amount": "$2.00",          "startedAt": "2026-10-12T10:01:00.000Z"        },        "wallet": null,        "composite": null,        "custom": {          "flow": "signup"        }      }    ],    "notFound": [      "cmgl5zzzz0000notreal0000"    ]  }}
{  "statusCode": 400,  "statusDetail": {    "status": "ERROR",    "message": "Provide between 1 and 10 `ids`, separated by commas."  },  "result": {}}
{  "statusCode": 500,  "statusDetail": {    "status": "ERROR",    "message": "Could not complete the request."  },  "result": {}}

List Customer Usage Log GET

One customer's usage history — credit, outcome, unit, wallet and completed composite occurrences — merged into one feed sorted by time. Cursor-paginated: pass `limit`/`cursor` and read `nextCursor` back; `null` means the last page. Narrow by date with `from`/`to`.

Manage a customer's credit balance POST

Next Page