Billing agent usage to your clients

If an agent works for your clients, sooner or later you have to pass the consumption on. AI Tasker does not issue invoices or manage your margin, but it does leave the trace you need to compute it: consumption per workspace, activity per credential and a transaction ledger that is never erased. This guide is how to read it without inventing anything, and where the platform’s claims end.

The unit you bill: the workspace

The workspace is the unit of consumption, quota and isolation. If a client has their own workspace, the data is already separated: you do not need to tag every operation with a client, because the workspace already is one. The practical rule is one workspace per client, leaving projects for that client’s internal organisation.

Two clients in one workspace cannot be separated afterwards: consumption aggregates at workspace level and per-key activity does not say which client a project belongs to. Splitting into workspaces from day one is far cheaper than rebuilding the split at month end.

Read 1: period consumption

GET /api/usage?period=YYYY-MM returns, per workspace, the applied plan, the quota and what has been used, plus the breakdown per credential. It is the read behind the "usage" line of your invoice.

Consumption for a specific period.

curl -s "https://api.ai-tasker.theboomer.dev/api/usage?period=2026-10" \
  -H "x-api-key: atkr_your_key"

# {
#   "workspaceId": "...",
#   "plan": "free",
#   "period": "2026-10",
#   "quota": {
#     "agent":     { "limit": 100, "used": 87, "remaining": 13, "paidWithCredits": 4 },
#     "hosted_ai": { "limit": 100, "used": 12, "remaining": 88 }
#   },
#   "byAgent": [ { "apiKeyId": "...", "used": { "agent": 61, "hosted_ai": 0 } } ]
# }

quota.agent.used counts agent operations in the period (reads and mutations, one unit each).
quota.hosted_ai.used counts hosted AI operations (sprint planning, task generation, breakdown).
quota.agent.paidWithCredits is the number almost nobody looks at and it explains the rest: operations paid by the owner balance instead of the plan quota. Without it, an agent working beyond the plan looks like it consumes nothing.
byAgent[].used splits the same consumption per API key, which is what lets you say "this client spent this much with this agent".

Read 2: activity for one credential

When the client asks "why did you charge me for this?", the answer is not in the aggregate but in the events: which method and route was called, and in which time bucket.

Activity for one key over the last 168 hours.

curl -s "https://api.ai-tasker.theboomer.dev/api/apikeys/KEY_ID/usage?hours=168" \
  -H "x-api-key: atkr_your_key"

# { "total": 412, "buckets": [ { "bucket": "2026-10-26T10:00:00.000Z", "count": 37 } ], "events": [...] }

hours ranges from 1 to 720 (30 days). Buckets are hourly up to 48 hours and daily beyond that, which is exactly what you need to spot a polling loop without opening events one by one.

Read 3: the accounting trail

The credit history is the part that works as evidence: every purchase, every consumption and every refund is recorded. And there is one guarantee worth knowing: archiving or purging a workspace for inactivity never touches the transaction ledger, so a client’s history survives even after their workspace is gone.

Movement types as they appear in GET /api/credits/history.
Movement	What it means for the invoice
Credit pack purchase	Credits coming in; the base of what you can pass on
`AGENT_OPERATION`	Consumption paid by the owner balance because the plan quota was exhausted
`AGENT_OPERATION_REFUND`	Refund of a failed operation: not billed
AutoRefill	Monthly subscription that tops up; grows 20 % per month until month 12

An honest split in three columns

AI Tasker gives you the consumption; the price on top is yours.
Item	Where the data comes from	Passed to the client
Seats (2.00 €/month per unit)	AI Tasker billing: members, API keys and approved workspaces	Your call: it is your cost or a pass-through
Agent operations	`quota.agent.used` + `paidWithCredits`	Depends on your model: per operation, per tier or included
Hosted AI operations	`quota.hosted_ai.used`	The highest real cost; worth billing separately
Prepaid credits	`GET /api/credits/history`	Consumption AI Tasker already charged you (or the client, if they own the account)

What AI Tasker does not do

It does not invoice your clients. No tax documents, no VAT, no numbering series: that lives in your billing system.
It does not split by project for billing. The reliable breakdown is per workspace and per credential; below that, attribution is yours to build.
It does not block the end client. The walls (quota, daily guard, balance) are hit by your agent; if you want to cut a client off, revoke the credential or detach the workspace.
It does not compute your margin. Resale price, tiers and discounts are your decision.

Month-end close in five steps

Fix the period in UTC (YYYY-MM) and use the same one in every read: mixing months is the mistake that breaks the first invoice.
Pull GET /api/usage?period=YYYY-MM for every client workspace and store the response as evidence for the month.
Cross quota.agent.paidWithCredits with the credit history: those are the operations the quota did not cover.
Keep GET /api/apikeys/:id/usage for each client’s keys if you need to defend a specific line.
Archive the evidence outside AI Tasker: the transaction ledger is not erased, but your invoice must be explainable without platform access.

Usage data belongs to the workspace, and one key can reach several attached workspaces. If you share a credential between two clients you lose attribution: there is no way to separate afterwards which operation belonged to whom.

Pass agent usage on to a client in AI Tasker

Separate consumption per client, read quota and activity per credential, and keep the period evidence before invoicing.

Separate per client
One workspace per client; projects inside it for internal organisation.
One credential per agent
Each agent with its own API key, attached only to the workspaces it needs.
Read period consumption
GET /api/usage?period=YYYY-MM per workspace: quota, used, remaining and operations paid with credits.
Keep the evidence
Export the response and, to defend a specific line, the key activity with GET /api/apikeys/:id/usage.
Cross with the history
GET /api/credits/history for purchases, consumption and refunds: the trail that is never erased.
Invoice in your system
AI Tasker does not issue the end client invoice: export the numbers and bill with your own taxes and numbering.

Frequently asked questions

Does AI Tasker invoice my clients?

No. AI Tasker bills the account holder (seats and credits). Invoicing the end client, with your taxes and numbering, is yours.

Can I know how much each client consumed?

Yes, if each client has their own workspace: GET /api/usage?period=YYYY-MM returns quota and consumption per workspace plus the breakdown per API key.

What does `paidWithCredits` mean?

Operations paid from the owner balance because the plan quota was exhausted. Without that number, an agent working beyond the plan looks like it consumes nothing.

Is history lost if I archive the workspace?

No. Archiving and purging for inactivity never touch the transaction ledger: the accounting history remains.

Can I bill per project?

The reliable data is per workspace and per credential. To bill per project, split projects into separate workspaces: AI Tasker does not aggregate consumption by project.

How do I cut off a client who does not pay?

Revoke their API key (DELETE /api/apikeys/:id) or detach their workspace from a shared credential. The other clients keep working.

Sources

Plans, limits and operations (GET /api/plans)
https://api.ai-tasker.theboomer.dev/api/plans
API OpenAPI contract
https://api.ai-tasker.theboomer.dev/api/openapi.json
Usage and credits endpoints in /docs
https://api.ai-tasker.theboomer.dev/docs

Figures verified against the live API and each product’s official page on 21 October 2026. Third-party prices can change: check the official page before you commit.

Related guides

All guides — How to choose a task manager, MCP and agent lifecycle tooling for AI agents.
Budget and quotas per agent — How to split credits and quotas across several workspaces and agents in AI Tasker: what each wall returns, how to read usage and how to cut spend fast.
Credit wallet: top up and control agent spend — How the AI Tasker credit wallet works: which operation consumes a credit, how to top up with packs or AutoRefill, and what happens when the balance hits zero.
How agent usage is billed — How AI Tasker measures and bills agent usage: the 2 € billable unit, operations, credit packs and auto-refill. No surprises.
Security and per-workspace isolation — The AI Tasker security model: per-workspace isolation, credential encryption, key rotation, quotas and an audit feed with double redaction.
Pricing — Real prices: free plan and a 2.00 €/month billable unit.
MCP integration — https://mcp.ai-tasker.theboomer.dev/mcp
/llms.txt — Machine-readable contract.