Task billing

Agree on pricing first

In Task Billing, a business owner or admin approves a policy for a client: currency, hourly rate, usage multiplier, and budget per task. A zero rate or multiplier means that component is free. Missing pricing is never treated as zero. Existing tasks retain their original policy; create a new policy for new rates.

The budget applies to each task, not to the API key or business as a whole. An agent with write permission can create multiple tasks. Review its instructions and workload accordingly.

Agent workflow

1. Call list_billing_policies and choose the approved client policy.
2. Call create_task with a policy ID, title and fresh UUID request ID.
3. Call start_task when active work begins. Call heartbeat_task every 30 to 60 seconds while working.
4. Call pause_task while waiting for a human, external approval, or idle resources. Call start_task to resume.
5. Call record_task_usage for known provider costs. Include the provider request reference, currency and evidence source; token counts and model are optional. Submit all usage before completion.
6. Call complete_task, then get_task_billing_preview. Completion freezes the record.
7. A human reviews the reported usage in Task Billing and approves a draft invoice. Sending is a separate action.

What counts as time

Billr measures elapsed time using server timestamps. Each heartbeat or stop records at most 120 seconds since the preceding heartbeat. Long gaps expire; they do not silently become billable hours. Preview totals include recorded time only, so complete or pause before reviewing a total.

This measures a reported active session, not CPU utilization, productive effort or independently verified work. Parallel activity within one task is counted once. Different tasks are independent and can overlap; do not use multiple tasks to charge twice for the same work.

Transparent calculation

time = round(active_seconds × hourly_rate / 3600, 2)
usage = round(sum(reported_provider_cost) × usage_multiplier, 2)
total = time + usage

For 36 active seconds at $100/hour and $2 of reported usage with a 1.5 multiplier, the total is $1 + $3 = $4. Billr adds no platform fee to this amount. A usage multiplier is the business's pricing decision, not a Billr fee.

Billr does not fetch provider invoices or infer prices from model names. Usage must use the policy currency. No exchange-rate conversion or estimated provider charge is applied. Inspect the original provider records before approving billing.

Retries and limits

Use a new UUID for each operation and reuse it with identical input on retries. A repeated request returns its original result. A provider request reference can be billed only once per business and provider. Reusing a request ID with different input fails.

Time stops growing at the task budget. Usage that would exceed it is rejected. Complete and review the task before authorizing additional work under a new policy. You cannot edit or delete an invoiced task.

Legacy log_time and log_expense remain available for manual records. They are separate from task billing; do not record the same work through both paths. Their create operations also require stable request IDs for safe retries.

The task walkthrough follows one task from an approved policy through usage reporting to human billing review, and choosing a key profile covers what an agent may do inside it.