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.
Name the customer on each call
Section titled “Name the customer on each call”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
AttributionConflictbefore 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)Which IDs are accepted
Section titled “Which IDs are accepted”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.
Refuse calls without a customer ID
Section titled “Refuse calls without a customer ID”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.
