How-to › Ship an SDK

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.

Audience
Platform team
Level
intermediate
Topic
Compose runtime features in an SDK
Languages
TypeScript, Go and Python
Verified

Read first: Wrap an SDK transport in a middleware chain

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Go RoundTripper counterA hand-written Go client, or any Go client that accepts your http.ClientIt sees concrete paths and every attempt, so the route matcher and the billing rule are yours to writeThe client is generated and already hands you the route template
httpx response event hookA hand-written Python client on httpx, where one hook should see every responseThe route template and the caller must ride in request extensions, set at every call siteYou cannot reach the call sites of a generated client
Kiota request adapter wrapperClients Kiota already generated, in any of its languages, with a counter you ownA wrapper per language, around an interface its documentation reserves for generated codeOne ledger shape must hold across languages without writing it in each
Provider billing exportSettling what was charged, across every process and every clientIt arrives about a day later and cannot say which of your callers spent whatYou need the number inside the process, the same day
sdkgen cost featureClients generated by sdkgen, where one options block should mean the same in every languageA rate table that never reads the response status, and totals that live in one processYour provider bills by status and reports no cost header
Swagger Codegen ApiClient subclassA Python client from Swagger Codegen, whose call_api still holds the route templateNo per-call argument for the caller, and one subclass or template per languageCallers 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.

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

  1. Amazon S3’s page on billing for error responses 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. ↩︎ Back to text

  2. 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 cache inside cost, so a response served from the cache is charged for money that was never spent. ↩︎ Back to text

  3. 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

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.