# How to attribute API cost per operation and per caller in an SDK

> Price each SDK call from a rate table, charge it to the operation and the caller that made it, and check the running totals against the provider's own bill.

Source: https://voxgig.com/howto/attribute-api-cost-per-operation-and-caller

- Audience: platform-team
- Level: intermediate
- Languages: typescript, go, python
- Verified: 2026-11-19
- Published: 2026-11-19

## Short answer

Attribute API spend in an sdkgen client by adding its `cost` feature, regenerating, and constructing the client with a rate per operation and a default `actor`. Pass `{ actor }` with a call to charge another caller. The client keeps totals per operation and per caller in `client._cost` and hands each finished call to a `sink`. List `retry` before `cost` in an array when your provider does not bill failed attempts, because the default order prices every attempt.

---
## You will need

Node 22 or later, an OpenAPI 3 document for the paid API, and the provider's price list. Verified
2026-11-19 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, and `@voxgig/sdkgen` 4.44.3.

The document here, `api.json`, describes a made-up API that charges 5 credits for a place search,
1 for a lookup, and 20 for a route. A stand-in server on the loopback interface plays the provider
and keeps its own bill. It bills a 2XX or 4XX response and not a 5XX, the rule
[Amazon S3 documents](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ErrorCodeBilling.html)
for its own requests.[^1] Layering transport behavior is covered in
[wrap an SDK transport in a middleware chain](/howto/wrap-an-sdk-transport-with-middleware).

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Go `RoundTripper` counter](https://pkg.go.dev/net/http#RoundTripper) | A hand-written Go client, or any Go client that accepts your `http.Client` | It sees concrete paths and every attempt, so the route matcher and the billing rule are yours to write | The client is generated and already hands you the route template |
| [`httpx` response event hook](https://www.python-httpx.org/advanced/event-hooks/) | A hand-written Python client on `httpx`, where one hook should see every response | The route template and the caller must ride in request extensions, set at every call site | You cannot reach the call sites of a generated client |
| [Kiota request adapter wrapper](https://learn.microsoft.com/en-us/openapi/kiota/abstractions) | Clients Kiota already generated, in any of its languages, with a counter you own | A wrapper per language, around an interface its documentation reserves for generated code | One ledger shape must hold across languages without writing it in each |
| [Provider billing export](https://docs.aws.amazon.com/cur/latest/userguide/what-is-cur.html) | Settling what was charged, across every process and every client | It arrives about a day later and cannot say which of your callers spent what | You need the number inside the process, the same day |
| [sdkgen `cost` feature](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md#cost) | Clients generated by sdkgen, where one options block should mean the same in every language | A rate table that never reads the response status, and totals that live in one process | Your provider bills by status and reports no cost header |
| [Swagger Codegen `ApiClient` subclass](https://github.com/swagger-api/swagger-codegen-generators/blob/master/src/main/resources/handlebars/python/api_client.mustache) | A Python client from Swagger Codegen, whose `call_api` still holds the route template | No per-call argument for the caller, and one subclass or template per language | Callers must be tagged per call in a language without context variables |

Voxgig maintains sdkgen. It is the subject of this page, and its row names what its rate table
cannot see.

The choice is between a counter you configure and one you write. sdkgen's feature is one options
block, with the same names in the TypeScript and Python targets generated for this page, and it
prices an attempt without reading the status. A wrapper around a Kiota or Swagger Codegen client
applies the provider's billing rule exactly, once per language. The billing export settles
disputes a day later and has never heard of your callers.

## Add the cost feature and regenerate

A feature's source has to be in the project before a client can switch it on. Name it when you
scaffold, or run `npx voxgig-sdkgen feature add cost` inside `.sdk` of an existing project.

```bash title="generate.sh"
npx --yes @voxgig/create-sdkgen@0.31.9 geodesk --def api.json --target ts --feature cost --feature retry
cd geodesk-sdk/.sdk
npm run generate
```

`npm run generate` writes the TypeScript SDK to `geodesk-sdk/ts`, with
`src/feature/cost/CostFeature.ts` in it. The feature's `active` option defaults to `false`, so a
client that never asks for it counts nothing. `retry` is added because the order of the two
decides what a retried call is charged.

## Price each operation and tag the caller

The rate table is the provider's price list, keyed `<entity>.<op>`. A helper turns a caller tag
into the control object a call takes as its second argument.

```js title="demo.mjs"
// The provider's price list in credits, copied by hand and keyed the way the
// cost feature looks a rate up: '<entity>.<op>', then '<op>', then '*'.
export const RATES = { 'place.list': 5, 'place.load': 1, 'route.create': 20 }

// Turn a caller tag into the per-call control the generated client reads.
export const as = (caller) => ({ actor: known(caller) })
```

Construct the client with a `cost` block. Its `actor` is the caller for any call that carries no
tag, and `sink` receives one record per finished operation.

```js title="demo.mjs"
  const client = new GeodeskSDK({
    base: api.base,
    feature: {
      cost: {
        active: true,
        currency: 'credits',
        rates: RATES,
        // The caller for any call that carries no tag of its own.
        actor: 'support',
        // Called once per finished operation, with the caller and the amount.
        sink: (record) => ledger.add(record.actor, `${record.entity}.${record.op}`, record.amount),
      },
    },
  })

  // The nightly job tags each call it makes.
  for (let i = 0; i < 12; i++) await client.Place().list({ q: 'du' }, as('nightly-sync'))

  // Checkout shares the client and tags its own calls.
  for (let i = 0; i < 6; i++) await client.Place().load({ id: 'pl_1' }, as('checkout'))
  await client.Route().create({ from: 'pl_1', to: 'pl_3' }, as('checkout'))

  // The support console passes no tag, so its calls fall to the constructor's actor.
  for (let i = 0; i < 3; i++) await client.Place().load({ id: 'pl_2' })
  await client.Place().list({ q: 'co' })
```

```bash
node demo.mjs
```

```text output
client._cost.ops, per operation
  place.list    13 calls   65 credits
  place.load     9 calls    9 credits
  route.create   1 call    20 credits
client._cost.actors, per caller
  nightly-sync  12 calls   60 credits
  checkout       7 calls   26 credits
  support        4 calls    8 credits
ledger fed by sink, per caller and operation
  nightly-sync  place.list    12 calls   60 credits  64%
  checkout      route.create   1 call    20 credits  21%
  checkout      place.load     6 calls    6 credits   6%
  support       place.list     1 call     5 credits   5%
  support       place.load     3 calls    3 credits   3%
client total 94 credits over 23 calls
provider bill 94 credits for 23 requests
```

`client._cost` keeps `ops` and `actors` as separate tallies, so it cannot say which caller ran
which operation. The `sink` can. Each record names the entity, the operation, the actor, the
amount, and the attempts, so a ledger keyed on both puts the nightly job's searches at 60 of 94
credits.

## Decide what a retried call is charged

The feature prices each HTTP attempt and `retry` multiplies attempts, so which one wraps the
other decides the charge. `retry.mjs` makes one `place.list` call under three arrangements.

```js title="retry.mjs"
const retry = { active: true, retries: 2, minDelay: 1, maxDelay: 5 }
const byTable = { active: true, currency: 'credits', rates: RATES }
const byHeader = { active: true, currency: 'credits', header: 'geodesk-credits', perUnit: 1 }

export const ARRANGEMENTS = [
  // A map is initialized in name order: cost first, then retry around it,
  // so cost prices every attempt.
  ['cost inside retry, priced by table', { cost: byTable, retry }],
  // An array is initialized in the order written: retry first, then cost
  // around it, so cost prices the retried call once.
  ['cost outside retry, priced by table', [{ name: 'retry', ...retry }, { name: 'cost', ...byTable }]],
  // Every attempt is priced by what the provider reports for it.
  ['cost inside retry, priced by header', { cost: byHeader, retry }],
]
```

```bash
node retry.mjs
```

```text output
one place.list call, answered 503, 503, 200
  the provider billed                    5 credits for 3 requests
  cost inside retry, priced by table    15 credits over 3 attempts
  cost outside retry, priced by table    5 credits over 1 attempt
  cost inside retry, priced by header    5 credits over 3 attempts
one place.list call, answered 503, 503, 503
  the provider billed                    0 credits for 3 requests
  cost inside retry, priced by table    15 credits over 3 attempts
  cost outside retry, priced by table    5 credits over 1 attempt
  cost inside retry, priced by header    0 credits over 3 attempts
```

A `feature` map is initialized in alphabetical order, and a feature initialized later wraps the
earlier ones. The map form therefore puts `retry` outside `cost`: one call became three priced
attempts, 15 credits against a bill of 5. sdkgen's reference defends that default on the grounds
that the upstream API charges a retry again.[^2] This stand-in does not. An array is initialized
in the order written, so listing `retry` first puts `cost` around the whole loop.

Neither table row survives the second case. The rate table never reads the status, so a call
that failed three times costs 15 credits or 5 on a bill of zero. Only the `header` row matches the
bill both times. `header` names a response header in which the provider reports the charge,
`perUnit` prices one unit of it, and a 503 carries none.

## Count the same spend in Kiota and Swagger Codegen

Neither generator has a cost option. None of the thirteen handlers on Kiota's
[middleware page](https://learn.microsoft.com/en-us/openapi/kiota/middleware) counts spend, and
none of the seven options Swagger Codegen prints for its Python target adds a hook. Each generates
one choke point that still holds the route template, so the counter is a wrapper there.

Every operation Kiota generates calls the request adapter once, with a request information object
carrying `httpMethod` and `urlTemplate`. `kiota-cost.mjs` wraps the adapter in a `Proxy`, and a
caller tag travels as a request option.

```js title="kiota-cost.mjs"
/** Wrap a request adapter so each operation is charged to a caller and a route template. */
export function metered(adapter, { prices, ledger, caller }) {
  return new Proxy(adapter, {
    get(target, name) {
      const member = Reflect.get(target, name, target)
      if (typeof member !== 'function' || typeof name !== 'string' || !name.startsWith('send')) return member
      return async (requestInfo, ...rest) => {
        const route = `${requestInfo.httpMethod} ${templatePath(requestInfo.urlTemplate ?? '')}`
        // A route nobody priced is refused before it spends anything.
        if (!prices.has(route)) throw new RangeError(`no price for ${route}`)
        const tag = requestInfo.getRequestOptions()[CALLER_OPTION]?.caller ?? caller
        try {
          const result = await member.call(target, requestInfo, ...rest)
          ledger.add(tag, route, prices.get(route))
          return result
        } catch (err) {
          // Kiota raises an API error carrying the status. Charge it when the provider did.
          if (billable(err?.responseStatusCode)) ledger.add(tag, route, prices.get(route))
          throw err
        }
      }
    },
    set: (target, name, value) => Reflect.set(target, name, value, target),
  })
}
```

```bash
node kiota-cost.mjs
```

```text output
Kiota client, counted at the request adapter
  nightly-sync  GET /places            12 calls   60 credits
  checkout      POST /routes            1 call    20 credits
  checkout      GET /places/{placeId}   6 calls    6 credits
  support       GET /places             1 call     5 credits
  support       GET /places/{placeId}   3 calls    3 credits
counted 94 credits over 23 operations
provider bill 94 credits for 25 requests
```

The provider saw 25 requests because Kiota's default retry handler repeated two 503 responses
below the adapter. The count still matches, because the wrapper applies the billing rule itself.
Kiota's documentation keeps the adapter interface for generated code and documents middleware
as the extension point. A middleware sees concrete URLs and, placed after the retry handler, every attempt. Kiota
also prints that its TypeScript target is in preview. The Go and Python builders it generated from
this document call the adapter the same way.

Swagger Codegen's Python client sends every operation through `ApiClient.call_api`, whose first
two arguments are the route template and the method, so a subclass counts there. The generated
methods reject unknown keyword arguments, so a per-call tag travels in a context variable.

```python title="swagger_cost.py"
    def call_api(self, resource_path, method, *args, async_req=None, **kwargs):
        route = f"{method} {resource_path}"
        # A route nobody priced raises KeyError here, before it spends anything.
        price = self._prices[route]
        # Read the tag on the calling thread. The pool's threads do not inherit it.
        caller = _caller.get() or self._default_caller
        work = (route, price, caller, resource_path, method, args, kwargs)
        if async_req:
            return self.pool.apply_async(self._metered, work)
        return self._metered(*work)

    def _metered(self, route, price, caller, resource_path, method, args, kwargs):
        try:
            result = super().call_api(resource_path, method, *args, **kwargs)
        except ApiException as err:
            # The generated client raises on any status outside 2XX. Charge it when the provider did.
            if billable(err.status):
                self._ledger.add(caller, route, price)
            raise
        self._ledger.add(caller, route, price)
        return result
```

```bash
PYTHONPATH=pydeps:swagger python3 swagger_cost.py
```

```text output
Swagger Codegen client, counted in call_api
  nightly-sync  GET /places            12 calls   60 credits
  checkout      POST /routes            1 call    20 credits
  checkout      GET /places/{placeId}   6 calls    6 credits
  support       GET /places             1 call     5 credits
  support       GET /places/{placeId}   3 calls    3 credits
counted 94 credits over 23 operations
provider bill 94 credits for 23 requests
```

To put the counter in every regenerated client instead, edit a copy of the
[`api_client` template](https://github.com/swagger-api/swagger-codegen-generators/blob/master/src/main/resources/handlebars/python/api_client.mustache)
and pass its directory to `generate` with `-t`.

## Key a transport counter by route template

A hand-written client has no adapter in front of its transport, so the counter is a
`RoundTripper` in Go or a response event hook in `httpx`. Both see the concrete URL of every
attempt. Keyed on that path, a counter mints a series per id, the unbounded label
[Prometheus warns against](https://prometheus.io/docs/practices/naming/). Match the path back to
its template, and read the caller from the request's context.

```go title="roundtripper.go"
// RoundTrip sends the request on and charges it if the provider billed it.
func (m *Meter) RoundTrip(req *http.Request) (*http.Response, error) {
	resp, err := m.Next.RoundTrip(req)
	if err != nil || !billable(resp.StatusCode) {
		return resp, err
	}
	caller, _ := req.Context().Value(callerKey{}).(string)
	if caller == "" {
		caller = m.Caller
	}
	// One series for everything unpriced, so a stray path cannot mint a series of its own.
	key, price := "unmatched", 0
	if route, ok := m.match(req.Method, req.URL.EscapedPath()); ok {
		key, price = route.Method+" "+route.Template, route.Price
	}
	m.mu.Lock()
	defer m.mu.Unlock()
	if m.spend == nil {
		m.spend = map[[2]string]Cell{}
	}
	cell := m.spend[[2]string{caller, key}]
	m.spend[[2]string{caller, key}] = Cell{cell.Calls + 1, cell.Amount + price}
	return resp, nil
}
```

```bash
go run roundtripper.go
```

```text output
12 lookups of 12 places, one of them repeated after a 503
  keyed by concrete path    12 series
  keyed by route template    1 series
per caller and route template
  nightly-sync  GET /places/{placeId}   8 calls    8 credits
  checkout      GET /places/{placeId}   4 calls    4 credits
counted 12 credits
provider bill 12 credits for 13 requests
```

The transport saw the 503 and its repeat as two requests and charged one, because it applies the
billing rule to each response. An `httpx` hook receives the response and reaches the request
through it, so the template and the caller go in the request's
[extensions](https://www.python-httpx.org/advanced/extensions/) at each call site.

## Check it worked

Run the suite. It drives all four counters against stand-ins that keep their own bills.

```bash
node --test cost.test.mjs
```

```text output
1..20
# tests 20
# suites 0
# pass 20
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

`# pass 20`. The first test asserts per-caller totals of `60`, `26`, and `8` credits against the
fixed rate table and the provider's bill of `94`. The last two run the Python and Go suites.

## When it goes wrong

The client's total is below the bill. An operation has no rate, so the feature priced it at zero
and its `sink` record carries `source: 'none'`. Alarm on that value and add the rate.

Spend is missing from `client._cost.actors`. A caller tag matched a member of `Object.prototype`.

```bash
node unsafe-tag.mjs
```

```text output
actor "checkout"    2 credits spent, 1 in client._cost.actors, a new {} has calls: undefined
actor "constructor" 2 credits spent, 0 in client._cost.actors, a new {} has calls: undefined
actor "__proto__"   2 credits spent, 0 in client._cost.actors, a new {} has calls: NaN
```

The generated feature keeps its tallies in plain objects, so `__proto__` also puts `calls` and
`amount` on `Object.prototype`, where every object in the process inherits them. Check each tag
against a fixed set before it reaches the client, as `known` does in `callers.mjs`.

Two workers each report half the spend. Totals live on one client object in one process. Forward
each `sink` record to the metrics system you already aggregate with.

## When not to do this

Do not treat any of these counts as the invoice. Each prices what one process saw, from a table
somebody copied by hand. AWS's Cost and Usage Reports, for one provider, update about once a day
and call their month-to-date figures estimates.[^3] Reconcile against the export, and believe the
export.

Do not adopt sdkgen to get a counter. If your clients are Kiota's already, the adapter wrapper
here is 24 lines and applies your provider's billing rule exactly, which sdkgen's rate table
cannot. If the client is Swagger Codegen's Python package, the subclass needs no regeneration.

Do not rely on sdkgen's rate table alone when the provider bills by status. A call that fails
outright is still charged a full rate.

Do not pass request data as a caller tag. A tenant id is an unbounded label, and one named
`__proto__` corrupts the process.

## Related how-tos

- [Wrap an SDK transport in a middleware chain](/howto/wrap-an-sdk-transport-with-middleware)

- [Write an audit record for every SDK call](/howto/write-an-audit-record-for-every-call)

- [Choose the pipeline stage where an SDK behavior should run](/howto/map-a-behaviour-to-a-pipeline-stage)

- [Account for tokens and cost per agent task](/howto/account-for-tokens-and-cost-per-task)

- [Set a client-side spend budget that stops SDK calls](/howto/set-a-spend-budget-that-stops-calls)

## Last verified

Verified 2026-11-19 against Node 22.23.5, Python 3.13.18, Go 1.24.7, `@voxgig/create-sdkgen`
0.31.9, `@voxgig/sdkgen` 4.44.3, Kiota 1.38.0 with its TypeScript runtime at 1.0.0-preview.114,
and Swagger Codegen 3.0.85. Every output block is what the command preceding it printed. The
three clients were generated once by `generate.sh` and committed. The project's Python target
was generated and run once with the same options, and is not committed. `httpx` was not run; its
hook and extensions come from its documentation. Swagger Codegen's `-t` option was read from its
help output, not exercised, and Kiota's Go and Python output was read, not run.

[^1]: Amazon S3's page on
[billing for error responses](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ErrorCodeBilling.html)
bills a 200 and a 4XX and exempts every 5XX. An `AccessDenied` costs the bucket owner nothing,
provided the request came from outside the owner's account or organization. The exemption is for
strangers.

[^2]: sdkgen's [features reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md#cost)
says a retried call is charged again because the upstream API charges it again. The same section
says of its own ordering that the default gets it wrong. A map puts `cache` inside `cost`, so a
response served from the cache is charged for money that was never spent.

[^3]: AWS's page on
[Cost and Usage Reports](https://docs.aws.amazon.com/cur/latest/userguide/what-is-cur.html) gives
the update frequency three ways: once a day, at least once a day, and up to three times a day. It
adds that the updates received during a month are estimates. The authoritative figure is
authoritative at month end.