Skip to content

Attribution

Attribution fields let Agent FinOps and its run receipts answer who spent money and why.

Field Meaning
business_subject_ref Stable customer / account / subject key used for commercial attribution
feature_id Product feature or capability that triggered the spend
workflow_id Named workflow or automation that owns the work
run_id One execution of a workflow (retryable unit of work)
operation_id One logical operation inside a run
attempt_id One provider attempt; retries get a new attempt id

Pass these into monitor(...) (and related helpers) so reservations, denials, and settlements stay joinable across the SDK, Agent FinOps and run receipts.

Immutable attribution on a stream/call attempt must not be rewritten mid-flight once the attempt has started.

A per-customer limit in Agent FinOps (dimension business_subject) applies only to calls whose reservation carries that customer’s ID as business_subject_ref. A call without one is checked against the organization and workspace limits only.

from kazenai_finops import use_attribution # or: from kazenai import use_attribution
with use_attribution(business_subject_ref="cust_123"):
monitored.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Summarize this ticket"}],
)
  • Use the same ID the limit was set for.
  • When a client only ever serves one customer, monitor(..., business_subject_ref="cust_123") names that customer on every call instead.
  • If both name a customer and the IDs differ, the call raises AttributionConflict before it reaches the provider.

The ID is held in a context variable. Calls in the same thread, and in asyncio tasks started inside the with block, carry it. A thread started inside the block, such as a ThreadPoolExecutor worker, does not, so its calls meet only the organization and workspace limits. Submit the work in a copy of the current context to carry the ID:

import contextvars
with use_attribution(business_subject_ref="cust_123"):
pool.submit(contextvars.copy_context().run, handle_ticket, ticket)

Agent FinOps checks each ID before it checks any limit, and refuses the call if one isn’t accepted:

  • Customer ID (business_subject_ref): 1 to 128 characters, starting with a letter or digit, then letters, digits and . _ : @ -. Spaces around it are trimmed. Words that mean “no customer” (unknown, none, null, default, anonymous, unattributed) are refused, so they are never billed as a customer.
  • Feature and workflow IDs (feature_id, workflow_id): 1 to 128 lowercase letters, digits and . _ -, starting with a letter or digit.

A refused ID raises InvalidAttribution (kazenai 1.2.6 and later) with the reason, for example “business_subject_ref has characters that aren’t allowed: space”. The receipt says the same and never stores the ID itself. Use an opaque ID such as cust_123, not a name or an email address.

monitor(..., require_customer_id=True) (kazenai and kazenai-finops 1.2.1 and later) refuses any call that names no customer ID. The call raises CustomerIdRequired before it reserves budget or reaches the provider, so a forgotten use_attribution block or a worker thread without the copied context fails loudly instead of skipping the customer’s limit. It is off by default.