Usage and time logs

Two reporting surfaces sit alongside the fleet: usage counters reported by leases, and time logs for human work. See Authentication. Replace https://cadence.example.com with your instance's address.

Lease usage

GET /api/v1/lease_usages; MCP lease_usages_list. Needs read.

Scope the query to a single lease or a whole space — over the API with ?lease=<id> or ?space=<key>, over MCP with lease or space. Without either, the API refuses with 422 and missing_scope (space or lease is required).

Filter by from and to (ISO-8601 bounds — from inclusive, to exclusive), pool, worker_version, task_type, image, token (the id of the serving LLM-provider token), and registration (the serving token's vendor). Each raw row carries lease_id, counter, amount, unit, reported_at, and idempotency_key.

Pass group_by — a comma-separated subset of counter, pool, worker_version, task_type, image, day, token, and registration — to sum the counters per group instead. A token group reads as the token's label and its vendor; a registration group reads as the vendor. Usage from a lease that was served no token groups under no token — its token and registration are empty. An unknown group_by key is refused with group_by must be a comma-separated subset of the allowed keys.

curl "https://cadence.example.com/api/v1/lease_usages?space=OPS&group_by=counter,day" \
  -H "Authorization: Bearer smc_your_token_here"

Time logs

A time log records a human work session on a task. POST /api/v1/time_logs to start one, POST .../:id/complete to end it, POST .../:id/report_usage to add a usage counter, and GET /api/v1/time_logs[/:id] to read your own; MCP time_logs_create, time_logs_complete, time_logs_report_usage, and time_log_usages_list.

Start a session by naming the task:

curl -X POST https://cadence.example.com/api/v1/time_logs \
  -H "Authorization: Bearer smc_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "task_key": "OPS-42" }'

A time log belongs to the operator who started it. You may hold only one open session per task at a time — starting a second is refused with user already has an open time log for this task — and you must be a member of the task's space. Acting on someone else's time log is refused with 403 and time_log_owner_mismatch. Completing a session records its wall-clock duration as a usage counter; reporting usage takes a counter, amount, unit, and idempotency_key, and is idempotent per session.

A read time log carries id, its task, user_id, started_at, ended_at (null while the session is open), and auto_closed_at (null unless the session was auto-closed — see below).

A stale session is auto-closed at a one-hour cap

If a session is left open — the process running it dies, or the operator never completes it — Cadence closes it for you rather than let it stay open and never settle. Once a session has been open longer than four hours, a recurring sweep closes it: it stamps ended_at at one hour past started_at, stamps auto_closed_at with the moment it closed, and records the session's duration as a flat one hour (3600 seconds), whatever the real elapsed time. It writes a time_log_auto_closed activity on the task.

The one-hour figure is a cap on what an abandoned session bills, not the real span: the sweep only reaches sessions already open past four hours, and an abandoned session should not bill for however long it happened to sit open.

Completing an auto-closed session is refused

Once a session has been auto-closed, completing it is refused rather than treated as a no-op — otherwise an operator who stepped away and returned could believe work done since was logged. POST /api/v1/time_logs/:id/complete returns 422 with error code time_log_auto_closed; over MCP, time_logs_complete returns an invalid-arguments error. Both carry the same message:

This session was closed automatically at 2026-05-01T11:00:00Z and billed at one hour. Start a new session to record anything worked since.

To record work done after the cap, start a new session on the task.