Run a billable task from start to review

Tasks bill active time and reported provider usage under a pricing policy a person approved. Agents can create, start, pause, heartbeat, report usage and complete a task, but they cannot approve pricing or invoice it; completion freezes the work for human review.

Written and reviewed by the Billr team. Published 2026-09-20, last reviewed 2026-09-20.

Who this is for: People billing agent work by the task or by provider usage rather than by hand-logged hours.
Billr capabilities used: list_billing_policiescreate_taskstart_taskheartbeat_taskpause_taskrecord_task_usagecomplete_taskget_task_billing_preview

What you need first

A pricing policy that already exists and was approved by a person; list_billing_policies returns the ones available.
A key with the Read and draft profile, which covers every task tool.
The provider and model details you intend to report, if the task bills usage as well as time.

Step by step

01Read the approved policies
list_billing_policies returns human-approved rates, usage multipliers, currencies and budgets. Pricing is not something an agent can create or approve.
Example
```
list_billing_policies  {}
```

02Create the task

policy_id, title and request_id are required. The task starts paused so nothing is billed before the work actually begins.

create_task  {
  "request_id": "6f1b3d97-2c84-4a50-9e73-8b4d1f6a2c05",
  "policy_id": "0d9c2b64-7f13-4e88-9a25-1c6b3e8d4f70",
  "title": "Schema markup remediation"
}

03Start, heartbeat and pause
start_task begins recording active time, heartbeat_task keeps a slow run alive, and pause_task stops the clock without closing the task. Each call carries its own request_id.
Example
```
start_task  {
  "request_id": "9b2e5c41-6a07-4d38-8f52-3e7a1c9b0d64",
  "task_id": "c8a3f0d5-4b17-4e92-9c60-2d5b8f1a7e39"
}
```

04Report provider usage

record_task_usage needs the provider, a provider request id, the cost and its currency plus a source, with optional model and token counts. Reporting is idempotent on the provider request id, so a replayed webhook does not double-bill.

record_task_usage  {
  "request_id": "3c7d1a86-5e29-4b04-9f71-6a2d8c4b1e95",
  "task_id": "c8a3f0d5-4b17-4e92-9c60-2d5b8f1a7e39",
  "provider": "anthropic",
  "model": "claude-sonnet-4",
  "provider_request_id": "req_01HZY8QK4M",
  "cost": 1.87,
  "currency": "USD",
  "input_tokens": 18450,
  "output_tokens": 2210,
  "source": "agent"
}

05Complete and read the preview
complete_task freezes the work for review and cannot be undone. get_task_billing_preview then returns time_amount, usage_amount, total, currency and requires_human_review, with a review url for the person who approves it.
Example
```
complete_task  {
  "request_id": "d7a4f0b8-3c61-4e29-8b05-9f2d6a1c4e73",
  "task_id": "c8a3f0d5-4b17-4e92-9c60-2d5b8f1a7e39"
}
```

Worked example

Fictional account, field names as returned by the server

You say

Create and start the schema remediation task, report this run's usage, then complete it for review.

Your agent calls

list_billing_policies {}
create_task { "request_id": "6f1b3d97-2c84-4a50-9e73-8b4d1f6a2c05", "policy_id": "0d9c2b64-7f13-4e88-9a25-1c6b3e8d4f70", "title": "Schema markup remediation" }
start_task { "request_id": "9b2e5c41-6a07-4d38-8f52-3e7a1c9b0d64", "task_id": "c8a3f0d5-4b17-4e92-9c60-2d5b8f1a7e39" }
record_task_usage { "request_id": "3c7d1a86-5e29-4b04-9f71-6a2d8c4b1e95", "task_id": "c8a3f0d5-4b17-4e92-9c60-2d5b8f1a7e39", "provider": "anthropic", "model": "claude-sonnet-4", "provider_request_id": "req_01HZY8QK4M", "cost": 1.87, "currency": "USD", "source": "agent" }
complete_task { "request_id": "d7a4f0b8-3c61-4e29-8b05-9f2d6a1c4e73", "task_id": "c8a3f0d5-4b17-4e92-9c60-2d5b8f1a7e39" }

Response from complete_task: the top-level keys are what the handler returns, and the inner task record is illustrative

{
  "result": {
    "task_id": "c8a3f0d5-4b17-4e92-9c60-2d5b8f1a7e39",
    "status": "completed"
  },
  "review_url": "https://billr.cc/tasks"
}

Limits and gotchas

Agents cannot create or approve pricing policies, and task pricing always needs a person.
Completing a task is final; it freezes the amounts for billing review rather than invoicing them automatically.
Task billing is separate from logged time: a task bills its own recorded active seconds and reported usage.
Budgets belong to the policy, so a task can run out of budget before the work is finished.

Troubleshooting

create_task says the policy is unknown: Run list_billing_policies for the business and use an id it returns. A policy from another business is out of scope.
Usage appears twice: The provider request id has to be stable. Reuse the same provider_request_id and request_id when replaying the same event.
The preview says a human review is required: That is the normal state until a person approves it in the app at the returned review_url; agents cannot skip that step.

Sources

Reviewed 2026-09-20 against Billr's own tool implementations and the client documentation linked above.