Skip to content

Track cost per customer

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

Adding up session costs by customer lets you bill your own customers for what they use, or find the customers who cost the most. Tag each session with the customer's ID in metadata. After the session ends, read its cost from the API, and add the costs up by that ID. A session's cost uses your plan's rates, and on Launch and Scale, it counts browser time by the second, as your invoice does. See Pricing.

Before you begin

Put your Steel API key in the STEEL_API_KEY environment variable, and install the Steel SDK with npm install steel-sdk or with pip install steel-sdk in a virtual environment. In Go and Rust, each program is the main.go of a module or the src/main.rs of a Cargo project, set up as the Go and Rust SDK pages show.

1. Tag sessions with metadata

Add the customer's ID to metadata when you create the session. Metadata is a flat set of keys and values that Steel keeps with the session. You can filter the list of sessions by it, and the session viewer in the dashboard shows it.

This program creates a session for one customer, prints its metadata, and releases it.

tag.mts
import Steel from "steel-sdk";

const client = new Steel();
const session = await client.sessions.create({
  metadata: { customer_id: "cus_1042", job_id: "job-7731" },
});

try {
  console.log(session.id, session.metadata);
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx tag.mts

The program prints the session's ID and metadata:

d06c61eb-8a3e-437c-bbb8-32b1648d2b1a { customer_id: 'cus_1042', job_id: 'job-7731' }

Use the same key name on every session, and set it in the one place in your code that creates sessions, so that no session is missed. Steel stores every value as a string. Do not put secrets in metadata, because Steel shows it in the dashboard. Add metadata has the rules for keys and values, and shows how to change metadata after a session starts.

2. Read each session's cost

Call sessions.cost with the session ID after you release the session. A live session's cost is not final, so the API returns 409 until the session ends. Steel writes the final usage a few seconds after the release, and until then the call returns a cost of zero. So this code reads the cost every 2 seconds until it is final: the call no longer fails with 409, and the cost is more than zero. It stops with an error after 30 seconds. In Go, a deferred release runs only when run returns, so release the session before this call.

async function finalCost(sessionId: string) {
  const deadline = Date.now() + 30_000;
  for (;;) {
    try {
      const cost = await client.sessions.cost(sessionId);
      if (cost.totalCost > 0) return cost;
    } catch (error) {
      if (!(error instanceof Steel.ConflictError)) throw error;
    }
    if (Date.now() > deadline) throw new Error(`The cost of session ${sessionId} is not final after 30 seconds.`);
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
}

const cost = await finalCost(session.id);
console.log(JSON.stringify(cost, null, 2));

In Rust, this code needs cargo add serde_json.

{
  "id": "de53d365-d381-43a8-a9be-308f2f091533",
  "currency": "usd",
  "unit": "dollar",
  "totalCost": 0.000022,
  "usage": {
    "browser": {
      "value": 1,
      "unit": "second"
    },
    "proxy": {
      "bytes": 0
    },
    "captcha": {
      "solves": 0
    }
  }
}

totalCost is the session's cost in US dollars, and usage shows what it comes from: browser time, bytes through Steel proxies and CAPTCHA solves.

The best time to read the cost is when your job ends. Store it in your own database next to the customer and job. Then a report can read your own database instead of calling the API once for each session. Session cost explains the response.

3. Add up cost by customer

To build a report from the API, list a period's sessions, read each one's cost, and add the costs up by the customer_id key. This program does that for November 2026.

cost-report.mts
import Steel from "steel-sdk";

const client = new Steel();
const micros = new Map<string, number>();

for (const status of ["released", "failed"] as const) {
  for await (const session of client.sessions.list({
    status,
    createdAfter: "2026-11-01T00:00:00Z",
    createdBefore: "2026-12-01T00:00:00Z",
  })) {
    const customer = session.metadata?.customer_id;
    if (!customer) continue;
    const cost = await client.sessions.cost(session.id);
    micros.set(customer, (micros.get(customer) ?? 0) + Math.round(cost.totalCost * 1e6));
  }
}

for (const [customer, total] of micros) {
  console.log(customer, (total / 1e6).toFixed(6));
}

In Rust, the program also needs cargo add futures-util. Run the program:

npx tsx cost-report.mts

The program prints one line for each customer, with the total in US dollars:

cus_1042 0.000088

The program adds the costs as whole millionths of a dollar, so that rounding errors do not add up over many sessions. It lists released and failed sessions in two passes, because the list leaves out failed sessions unless you ask for them. It skips live sessions, which have no final cost yet.

To report on one customer, pass metadata: { customer_id: "cus_1042" } to sessions.list, so that the list holds only that customer's sessions. For your organization's usage and bill, see Billing and usage.

Check that it worked

Run the report a few seconds after you release the session from Tag sessions with metadata, so that its cost is final. The report has a line for cus_1042, and its total is at least the totalCost that Read each session's cost printed for that session. If the total is 0.000000, the report ran before Steel wrote the final usage, so run it again.

Next steps