The map data provider’s invoice is one line: 94,000 credits. Four services and a nightly job share the key through one client library, and each team is sure its own share is small. The client made every one of those calls and kept no record of which operation it ran or who asked.
What you get
You will end up with a client that prices every call from a rate table and keeps running totals per operation and per caller, checked against the provider’s own bill. This is for you if several services or jobs share one paid API key.
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
for its own requests.1 Layering transport behavior is covered in
wrap an SDK transport in a middleware chain.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
Go RoundTripper counter | 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 | 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 | 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 | 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 | 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 | 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.
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.
// 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.
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' })
node demo.mjs
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.
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 }],
]
node retry.mjs
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 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.
/** 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),
})
}
node kiota-cost.mjs
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.
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
PYTHONPATH=pydeps:swagger python3 swagger_cost.py
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
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. Match the path back to
its template, and read the caller from the request’s context.
// 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
}
go run roundtripper.go
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 at each call site.
Check it worked
Run the suite. It drives all four counters against stand-ins that keep their own bills.
node --test cost.test.mjs
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.
node unsafe-tag.mjs
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
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.
Footnotes
-
Amazon S3’s page on billing for error responses bills a 200 and a 4XX and exempts every 5XX. An
AccessDeniedcosts the bucket owner nothing, provided the request came from outside the owner’s account or organization. The exemption is for strangers. ↩︎ Back to text -
sdkgen’s features reference 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
cacheinsidecost, so a response served from the cache is charged for money that was never spent. ↩︎ Back to text -
AWS’s page on Cost and Usage Reports 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. ↩︎ Back to text