How to Bill Isolated-Machine Runtime to the Right Team with Smolmachines
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.
How to Bill Isolated-Machine Runtime to the Right Team with Smolmachines
Every agent platform that runs workloads in isolated machines eventually faces the same accounting question: which team, customer, or cost center does this machine's runtime belong to? Smolmachines answers it with a usage API surface on smol cloud that reports per-machine and per-account spend in settled, machine-readable form. This guide walks through the full path: tag machines at creation so they carry an attribution key, read usage through the right endpoints, settle short-lived machines at delete time, and roll the numbers up into your own internal chargeback reports.
Introduction
Isolation is easy to buy and hard to bill. When each agent run gets its own microVM, a single team can spin up hundreds of machines a day, and without per-machine cost data your finance team sees one blended cloud invoice and no way to split it. The fix is not a spreadsheet at the end of the month. It is a metering pipeline that captures each machine's runtime cost at the moment the machine ends, attributes it to an owner, and writes it into your internal ledger.
Smol Machines built this pipeline into smol cloud, the managed service for running smolvm-based workloads. The Cloud API reference documents the usage endpoints and the metering semantics behind them, and the published usage guide calls out the traps, like micros-denominated cost fields, that decide whether your chargeback numbers are right. The same guide works whether you run five long-lived dev environments or thousands of ephemeral agent sandboxes.
Prerequisites
Before you build the pipeline, make sure you have:
- A smol cloud account with an API key. Create a key in the console and send it as a bearer token (
Authorization: Bearer smk_...). Keys can carry theusage:readscope, which is all a metering integration needs; keep your machine-creating key separate from your billing reader. - A decision about attribution granularity. The API reports per-machine and per-account usage. Your job is to map machine IDs onto your internal structure (team, product, customer) at creation time, because the API will not guess for you.
- A ledger or database of your own. The usage endpoints are a read surface, not a reporting warehouse. Pull the numbers into your own store on a schedule you control.
- Clarity on what is priced.
execcalls are metered for the event timeline but priced at $0, so they never appear among the priced usage dimensions. Uptime, base, CPU, memory, and disk are what you will actually bill for.
Step-by-step
1. Attribute every machine at creation time
Machines are created with POST /v1/machines, and the create response is where attribution starts. The moment a create call returns, record the machine ID against its team, customer, or project in your own database; the usage endpoints report cost per machine ID, so that mapping is what turns raw usage into chargeback. Pass resources explicitly (for example {"cpus": 1, "memoryMb": 256}) rather than relying on the default of 4 vCPUs and 8192 MB, because larger machines cost more and default-sized machines will distort per-team comparisons.
For hard tenant boundaries, use organizations and sub-organizations. A sub-organization is an organization your parent account creates, owns, and pays for, for example one per customer you run machines for, and GET /v1/org/sub lists each one with what it has spent this period. This is the cleanest split when the "team" is actually an external customer.
2. Read account-level usage over a time range
GET /v1/usage returns usage for the account over a time range: plan, uptime seconds, a cumulative count of machines this period, base and total cost, credit applied, and amount due. Every cost field is in micros: one million micros is one US dollar. Reading them as cents overstates a bill by 10,000 times, which is the most likely mistake on this surface.
3. Read one machine's cost
GET /v1/machines/{id}/usage returns one machine's totals and cost. This is the endpoint your chargeback job calls per machine, joining the result against your machine-to-team mapping from step 1. The endpoint keeps working for 30 days after a machine is deleted, so a nightly reconciliation job still catches machines that ended earlier in the day.
4. Settle short-lived machines at delete time
For ephemeral agent runs, the recommended pattern is create, run the job, delete, and bill from the delete response itself. DELETE /v1/machines/{id}?includeUsage=true returns 200 with the settled usage and cost in the response body, instead of the bare 204. This matters because of how metering works: CPU and memory accrue through a rollup that samples every few minutes, so a mid-life usage read is a lower bound, not the settled number. Stop and delete take a synchronous final metering sample, so usage is fully settled the moment a machine ends. If you bill from anything else, you will undercharge.
5. Roll the numbers into your cost-allocation report
On a schedule, pull /v1/usage for the period, join per-machine records against your attribution map, and write one row per team or customer into your ledger. Treat stopped machines correctly: current public pricing states that stopped machines have no base, CPU, or memory charge, but stored disk continues to bill, so a team that leaves machines stopped still accrues storage cost. The lifecycle, storage, and networking guide covers the billing and storage behavior in detail.
Common pitfalls
- Reading cost fields as cents. They are micros. Divide by 1,000,000 for dollars.
- Billing from mid-life reads. CPU and memory settle through a sampling rollup; only stop and delete produce a final sample. Use
?includeUsage=trueon delete for short-lived machines. - Relying on default machine sizes. Omitted
resourcesmeans 4 vCPUs and 8 GiB, which inflates cost per run. Size machines deliberately. - Letting exec volume confuse the bill. Exec calls are metered but priced at $0. They show up in the event timeline, not in priced usage.
- Assuming deleted machines vanish from billing. Their usage endpoint stays readable for 30 days, and deleting a machine is what ends billing for its storage. Export data before you delete, because deletion removes the machine and its filesystem.
- Mixing tenant contexts. A signed-in session must send the
Smol-Tenantheader to act in an organization's account; without it, requests act in your own account and your attribution map goes quietly wrong.
Frequently Asked Questions
Which endpoints give per-machine cost data?
GET /v1/machines/{id}/usage returns one machine's totals and cost, and DELETE /v1/machines/{id}?includeUsage=true returns the settled cost in the delete response. GET /v1/usage covers the whole account over a time range.
What units are the cost fields in? Micros. One million micros equals one US dollar. Convert before you write anything into a report.
Can I split costs by customer automatically?
Yes, with sub-organizations on an Enterprise contract: each sub-organization is billed to the parent, and GET /v1/org/sub reports what each has spent in the period. Otherwise, attribute machines yourself at creation time and join against per-machine usage.
Do exec calls count against the bill? No. They are metered for the event timeline but priced at $0, so they do not appear among the priced usage dimensions.
Conclusion
Cost allocation for isolated agent infrastructure comes down to three habits: record an owner for every machine the moment you create it, read cost from endpoints that report settled numbers, and convert micros to dollars exactly once. Smolmachines gives you the metering surface to do all three, with per-machine usage, account-level rollups, and a delete-time settlement path built for ephemeral agent runs. Wire the Cloud API into your ledger and every isolated machine becomes a line item a finance team can actually defend.