enterprise_ai.finops
Source: sdks/python/src/enterprise_ai/finops/__init__.py. Back to the Python SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Class FinopsClient
/v1/finops.
Resource
FinopsClient.alerts
alerts() -> Any
List the FinOps alerts. Budget, quota and billing variance alerts of the tenant, newest first, with their message in the language of the request. One page only. Requires a reader role and a tenant principal.
Route: /v1/finops/alerts (GET).
This element takes no parameter.
Returns: Any. Decoded JSON answer of the operation "List the FinOps alerts".
Raises: the typed errors of the transport (Errors).
FinopsClient.check_budget
check_budget(agent: str | None = None, project: str | None = None, run: str | None = None) -> Any
Read the quota consumption. Each quota of the tenant with its current window and the cost and tokens used and reserved in it. Run quotas need run to find their window. Requires a reader role and a tenant principal.
Route: /v1/quotas/usage (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
agent | str | None | None | no | Agent used to resolve the windows. |
project | str | None | None | no | Project used to resolve the windows. |
run | str | None | None | no | Agent run whose run quota windows are read. |
Returns: Any. Decoded JSON answer of the operation "Read the quota consumption".
Raises: the typed errors of the transport (Errors).
FinopsClient.create_allocation_policy
create_allocation_policy(policy: dict[str, Any]) -> Any
Create a GPU allocation policy. Creates a policy that prices the GPU samples of the matching deployments and answers 201. The most specific deployment pattern wins. Cost of one sample of s seconds at P watts: GPU s / 3600 * gpu_hourly_cost, energy P * s / 3600 / 1000 * energy_kwh_price * pue, storage storage_gb * storage_gb_month_price * (s / 3600) / 730, total multiplied by 1 + overhead_pct / 100. Audited. Requires platform_admin.
Route: /v1/finops/allocation-policies (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
policy | dict[str, Any] | yes | Cost allocation policy to create, sent as the request body. |
Returns: Any. Decoded JSON answer of the operation "Create a GPU allocation policy".
Raises: the typed errors of the transport (Errors).
FinopsClient.create_media_price
create_media_price(price: dict[str, Any]) -> Any
Add a media price revision. Adds a dated price revision for a media unit and answers 201. A revision never rewrites an older one. The same unit, provider, resource and start date answers 409 media_price_exists; an invalid field 422 media_price_invalid. Audited. Requires finops or tenant_admin, and a tenant principal.
Route: /v1/finops/media-prices (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
price | dict[str, Any] | yes | Media price card to create (price per image, second of audio or video, character...). |
Returns: Any. Decoded JSON answer of the operation "Add a media price revision".
Raises: the typed errors of the transport (Errors).
FinopsClient.create_price_card
create_price_card(card: dict[str, Any]) -> Any
Create a price card. Creates a price card for the tenant (or a global one for a platform administrator without tenant) and answers 201. The card in force for the same provider, model pattern, region and usage type is closed at the new start date; a card starting later in the new validity answers 409 conflict. Unknown price keys, negative prices or a card without any price answer 422 price_card_invalid. Audited. Requires finops or tenant_admin (platform_admin for a global card).
Route: /v1/finops/price-cards (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
card | dict[str, Any] | yes | Price card to create, sent as the request body. |
Returns: Any. Decoded JSON answer of the operation "Create a price card".
Raises: the typed errors of the transport (Errors).
FinopsClient.estimate
estimate(provider: str, model_id: str | None = None, input_tokens: int = 0, output_tokens: int = 0, reasoning_effort: str | None = None, usage_type: str = 'llm', **extra: Any) -> Any
Estimate the cost of a call. Prices a planned call with the price card in force (most specific model pattern and region first), converts it to the tenant currency and checks it against the matching quotas, without reserving anything. Reasoning tokens are added according to the billing mode of the card. No card answers 404 price_card_not_found; a missing FX rate 422 fx_rate_missing. Requires a usage or reader role and a tenant principal.
Route: /v1/finops/estimate (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
provider | str | yes | Provider of the call (required). | |
model_id | str | None | None | no | Model of the call, matched against the model patterns of the price cards. |
input_tokens | int | 0 | no | Number of input tokens to price (default 0). |
output_tokens | int | 0 | no | Number of output tokens to price (default 0). |
reasoning_effort | str | None | None | no | Reasoning effort (none, minimal, low, medium, high, max) giving a default reserve of reasoning tokens. |
usage_type | str | 'llm' | no | Usage type, default llm. |
**extra | Any | no | Extra fields merged into the request body. |
Returns: Any. Decoded JSON answer of the operation "Estimate the cost of a call".
Raises: the typed errors of the transport (Errors).
FinopsClient.estimate_media_cost
estimate_media_cost(request: dict[str, Any]) -> Any
Estimate media costs. Prices up to 100 media items with the revision in force at their date (exact resource first, then the provider wide * revision). An item without price comes back with amount: null, status: unavailable and reason: price_unknown; total is given only when every item is priced in one currency (complete: true). Invalid items answer 422 media_price_invalid with the field. Requires a reader role or agent, and a tenant principal.
Route: /v1/finops/media-costs/estimate (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
request | dict[str, Any] | yes | items: 1 to 100 objects with unit (audio_second, image, video_second, gpu_second, storage_gb_month), provider, quantity (positive number), optional resource (default *) and at (ISO 8601, default now). |
Returns: Any. Decoded JSON answer of the operation "Estimate media costs".
Raises: the typed errors of the transport (Errors).
FinopsClient.fx_rates
fx_rates() -> Any
List the FX rates. Exchange rates (global ones and those of the tenant) by base, quote and newest date first, with their source. Requires a reader role.
Route: /v1/finops/fx-rates (GET).
This element takes no parameter.
Returns: Any. Decoded JSON answer of the operation "List the FX rates".
Raises: the typed errors of the transport (Errors).
FinopsClient.get_price_card
get_price_card(card_id: str) -> Any
Get a price card. One price card with its prices, tiers, validity and status. Unknown id: 404 not_found. Requires a reader role.
Route: /v1/finops/price-cards/{card_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
card_id | str | yes | Identifier (UUID) of the price card. |
Returns: Any. Decoded JSON answer of the operation "Get a price card".
Raises: the typed errors of the transport (Errors).
FinopsClient.gpu_allocation
gpu_allocation(start: str | None = None, end: str | None = None, **filters: Any) -> Any
Read the GPU cost allocation. Cost of the local GPU deployments over the window, computed from the GPU samples and the allocation policies, and shared between tenants in proportion to the GPU seconds of their usage events on each deployment. A tenant sees its own share; a platform administrator without tenant sees every tenant. Requires a reader role.
Route: /v1/finops/gpu/allocation (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
start | str | None | None | no | Start of the period (ISO 8601), sent as from; default one day before end. |
end | str | None | None | no | End of the period (ISO 8601), sent as to; default now. |
**filters | Any | no | Extra query parameters, sent as is. |
Returns: Any. Decoded JSON answer of the operation "Read the GPU cost allocation".
Raises: the typed errors of the transport (Errors).
FinopsClient.gpu_samples
gpu_samples(samples: list[dict[str, Any]]) -> Any
Ingest GPU samples. Stores GPU utilization samples (typically from DCGM), 1 to 10000 per call, used for the GPU cost allocation. One audit event per batch. Requires platform_admin.
Route: /v1/finops/gpu/samples (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
samples | list[dict[str, Any]] | yes | Samples to store, 1 to 10000. |
Returns: Any. Decoded JSON answer of the operation "Ingest GPU samples".
Raises: the typed errors of the transport (Errors).
FinopsClient.import_invoice
import_invoice(source: str, content: str, filename: str | None = None, **extra: Any) -> Any
Import a billing export. Parses a billing export of a provider, converts every line to the tenant currency and stores it, then answers 201 with the import (line count, total, period). An export that cannot be read answers 422 import_invalid with the reason. Run the reconciliation afterwards. Audited. Requires finops or tenant_admin, and a tenant principal.
Route: /v1/finops/reconciliation/imports (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
source | str | yes | Format of the export: openai, anthropic, aws_cur, azure, gcp or generic_csv. | |
content | str | yes | Content of the export as the provider gives it (JSON document or CSV text). | |
filename | str | None | None | no | Name of the imported file, kept for the history. |
**extra | Any | no | Extra fields merged into the request body. |
Returns: Any. Decoded JSON answer of the operation "Import a billing export".
Raises: ValueError, the typed errors of the transport (Errors).
FinopsClient.ingest_usage
ingest_usage(event: dict[str, Any]) -> Any
Ingest a usage event. Validates a Usage Event v1, prices it (measured cost in the tenant currency) and stores it; answers 201, or 200 with duplicate: true when the same event_id was already stored. An invalid event answers 422 usage_event_invalid with the errors; an event of another tenant 403 usage_tenant_mismatch. One audit event per call, never the payload. Requires finops, tenant_admin, agent or developer, and a tenant principal.
Route: /v1/finops/usage (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
event | dict[str, Any] | yes | Usage Event document (see usage_event); its event_id is the idempotency key. |
Returns: Any. Decoded JSON answer of the operation "Ingest a usage event".
Raises: the typed errors of the transport (Errors).
FinopsClient.ingest_usage_batch
ingest_usage_batch(events: list[dict[str, Any]]) -> Any
Ingest usage events in batch. Ingests up to 1000 usage events, each in its own savepoint: the answer lists every event as created, duplicate or error (with code, message and details) and the counts. More than 1000 events answer 413 batch_too_large; a body without an events list 422 validation_error. One audit event per batch. Requires finops, tenant_admin, agent or developer, and a tenant principal.
Route: /v1/finops/usage/batch (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
events | list[dict[str, Any]] | yes | Usage Event documents, sent as {events}. |
Returns: Any. Decoded JSON answer of the operation "Ingest usage events in batch".
Raises: the typed errors of the transport (Errors).
FinopsClient.list_allocation_policies
list_allocation_policies() -> Any
List the GPU allocation policies. Policies that turn GPU samples into a cost (GPU hourly cost, energy, PUE, storage and overhead) per deployment pattern and GPU model. Requires a reader role.
Route: /v1/finops/allocation-policies (GET).
This element takes no parameter.
Returns: Any. Decoded JSON answer of the operation "List the GPU allocation policies".
Raises: the typed errors of the transport (Errors).
FinopsClient.list_imports
list_imports() -> Any
List the billing imports. Billing exports imported by the tenant, with source, provider, file name, number of lines, total amount, currency and period. Requires a reader role and a tenant principal.
Route: /v1/finops/reconciliation/imports (GET).
This element takes no parameter.
Returns: Any. Decoded JSON answer of the operation "List the billing imports".
Raises: the typed errors of the transport (Errors).
FinopsClient.list_media_prices
list_media_prices(unit: str | None = None) -> Any
List the media prices. Dated media price revisions of the tenant by unit, provider, resource and date, with the list of supported units. An unknown unit answers 422 media_price_invalid. Requires a reader role and a tenant principal.
Route: /v1/finops/media-prices (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
unit | str | None | None | no | Only prices of this unit: audio_second, image, video_second, gpu_second or storage_gb_month. |
Returns: Any. Decoded JSON answer of the operation "List the media prices".
Raises: the typed errors of the transport (Errors).
FinopsClient.list_price_cards
list_price_cards(provider: str | None = None, model: str | None = None, at: str | None = None, include_retired: bool | None = None, **page: Any) -> Any
List the price cards. Price cards visible to the caller (global and tenant ones), by provider, model pattern and start date. Only active cards unless include_retired or at is given. One page only. Requires a reader role.
Route: /v1/finops/price-cards (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
provider | str | None | None | no | Only cards of this provider. |
model | str | None | None | no | Only cards whose model pattern matches this model id (case insensitive glob). |
at | str | None | None | no | Only cards in force at this date and time (ISO 8601), retired ones included. |
include_retired | bool | None | None | no | Include retired cards (default false). |
**page | Any | no | Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor. |
Returns: Any. Decoded JSON answer of the operation "List the price cards".
Raises: the typed errors of the transport (Errors).
FinopsClient.reconcile
reconcile(start: str | None = None, end: str | None = None) -> Any
Run the billing reconciliation. Allocates the imported billed lines of the period to the usage events: a line with a provider_request_id goes to that event, other lines are split pro rata of the measured cost of the events of the same provider, model and day (evenly when nothing was measured); lines without candidate event are reported as unmatched. Variance alerts are raised over the tenant threshold. Audited. Requires finops or tenant_admin, and a tenant principal.
Route: /v1/finops/reconciliation/run (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
start | str | None | None | no | Start of the reconciled period (ISO 8601), sent as from. |
end | str | None | None | no | End of the reconciled period (ISO 8601), sent as to. |
Returns: Any. Decoded JSON answer of the operation "Run the billing reconciliation".
Raises: the typed errors of the transport (Errors).
FinopsClient.reconciliation_report
reconciliation_report(start: str | None = None, end: str | None = None) -> Any
Read the reconciliation report. Measured against billed cost over the period, with the variance, the unmatched billing lines and the last 100 variance alerts. A from after to answers 422 validation_error. Requires a reader role and a tenant principal.
Route: /v1/finops/reconciliation/report (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
start | str | None | None | no | Start of the reported period (ISO 8601), sent as from. |
end | str | None | None | no | End of the reported period (ISO 8601), sent as to. |
Returns: Any. Decoded JSON answer of the operation "Read the reconciliation report".
Raises: the typed errors of the transport (Errors).
FinopsClient.record_usage
record_usage(event: dict[str, Any]) -> Any
Ingest a usage event. Validates a Usage Event v1, prices it (measured cost in the tenant currency) and stores it; answers 201, or 200 with duplicate: true when the same event_id was already stored. An invalid event answers 422 usage_event_invalid with the errors; an event of another tenant 403 usage_tenant_mismatch. One audit event per call, never the payload. Requires finops, tenant_admin, agent or developer, and a tenant principal.
Route: /v1/finops/usage (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
event | dict[str, Any] | yes | Usage Event document (see usage_event); its event_id is the idempotency key. |
Returns: Any. Decoded JSON answer of the operation "Ingest a usage event".
Raises: the typed errors of the transport (Errors).
FinopsClient.reserve
reserve(cost: number | string = '0', tokens: int = 0, scope: dict[str, Any] | None = None, ttl_seconds: int | None = None) -> Any
Reserve cost and tokens. Reserves an amount on every enabled quota matching the scope (tenant quotas always match; a user principal adds its own user scope) and answers 201 with the reservation, its items per quota and window, the soft quotas exceeded and its expiry. A hard quota that would be exceeded answers 429 quota_exceeded with Retry-After: 60, and nothing is reserved. Expired reservations are released first. Audited. Requires finops, tenant_admin, agent or developer, and a tenant principal.
Route: /v1/quotas/reserve (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
cost | number | string | '0' | no | Cost to reserve in the tenant currency, 0 to 10^15, default 0; converted to the currency of each quota. |
tokens | int | 0 | no | Tokens to reserve, 0 to 2^62, default 0. |
scope | dict[str, Any] | None | None | no | Who the call is for: keys project, agent, user, model, provider, run (or the same with _id), matched against the quota scopes. |
ttl_seconds | int | None | None | no | Lifetime of the reservation in seconds, 1 to 86400; default the tenant reservation_ttl_seconds (900). An expired reservation is released. |
Returns: Any. Decoded JSON answer of the operation "Reserve cost and tokens".
Raises: the typed errors of the transport (Errors).
FinopsClient.retire_price_card
retire_price_card(card_id: str) -> Any
Retire a price card. Marks the card retired and ends its validity at at (default now) when it was still open after that date. Past usage keeps the price it was costed with. Unknown id: 404 not_found. Audited. Requires finops or tenant_admin.
Route: /v1/finops/price-cards/{card_id}/retire (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
card_id | str | yes | Identifier (UUID) of the price card. |
Returns: Any. Decoded JSON answer of the operation "Retire a price card".
Raises: the typed errors of the transport (Errors).
FinopsClient.set_fx_rates
set_fx_rates(rates: dict[str, str]) -> Any
Set FX rates. Adds or replaces 1 to 1000 exchange rates (same base, quote and date: replaced) for the tenant, or global rates for a platform administrator without tenant, and answers the number updated with the full list. Conversions go through USD as pivot when no direct rate exists. Audited. Requires finops or tenant_admin (platform_admin for global rates).
Route: /v1/finops/fx-rates (PUT).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
rates | dict[str, str] | yes | Rates to add or replace, 1 to 1000. |
Returns: Any. Decoded JSON answer of the operation "Set FX rates".
Raises: the typed errors of the transport (Errors).
FinopsClient.settings
settings() -> Any
Read the FinOps settings. Currency, monthly budget, variance threshold and reservation lifetime of the tenant (defaults: USD, no budget, 10 percent, 900 seconds). Requires a reader role and a tenant principal.
Route: /v1/finops/settings (GET).
This element takes no parameter.
Returns: Any. Decoded JSON answer of the operation "Read the FinOps settings".
Raises: the typed errors of the transport (Errors).
FinopsClient.summary
summary(group_by: str = 'model', **filters: Any) -> Any
Summarize the spend. Usage events of the tenant grouped by one dimension, per currency: number of events, tokens, GPU seconds, estimated, measured and billed amounts (billed is null when nothing was reconciled). An unknown grouping answers 400 finops_group_by_invalid. Requires a reader role and a tenant principal.
Route: /v1/finops/summary (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
group_by | str | 'model' | no | Grouping: model (default), tenant, project, agent, provider, usage_type or day. |
**filters | Any | no | Extra query parameters, such as the period from and to (ISO 8601). |
Returns: Any. Decoded JSON answer of the operation "Summarize the spend".
Raises: ValueError, the typed errors of the transport (Errors).
FinopsClient.update_settings
update_settings(currency: str | None = None, monthly_budget: number | string | null = None, variance_threshold_pct: number | string | null = None, reservation_ttl_seconds: int | None = None) -> Any
Change the FinOps settings. Changes the given settings of the tenant; omitted or null fields keep their value. Audited (finops.settings.update). Requires finops or tenant_admin, and a tenant principal.
Route: /v1/finops/settings (PUT).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
currency | str | None | None | no | ISO 4217 currency in which the tenant costs are kept. |
monthly_budget | number | string | null | None | no | Monthly budget of the tenant, at least 0: the measured spend of the month is compared to it and budget alerts fire at the thresholds (50, 80 and 100 percent by default). It does not refuse calls by itself; use hard quotas for that. |
variance_threshold_pct | number | string | null | None | no | Variance between measured and billed cost, in percent, above which a variance alert is raised (default 10). |
reservation_ttl_seconds | int | None | None | no | Default lifetime of a quota reservation in seconds, greater than 0 (default 900). |
Returns: Any. Decoded JSON answer of the operation "Change the FinOps settings".
Raises: the typed errors of the transport (Errors).
FinopsClient.usage
usage(**filters: Any) -> Any
List the usage events. Usage events of the tenant with their units and their estimated, measured and billed costs, filtered and paginated. Requires a reader role and a tenant principal.
Route: /v1/finops/usage (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
**filters | Any | no | Query filters (project_id, agent_id, run_id, model_id, provider, usage_type, from, to...) and pagination (limit, cursor). |
Returns: Any. Decoded JSON answer of the operation "List the usage events".
Raises: the typed errors of the transport (Errors).
Functions
money
money(amount: Decimal | str | int, currency: str = 'EUR') -> dict[str, str]
{amount, currency} with a decimal string amount.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
amount | Decimal | str | int | yes | Amount as a Decimal, a decimal string or an integer; converted without float rounding. | |
currency | str | 'EUR' | no | ISO 4217 currency code (default EUR). |
Returns: dict[str, str]. Dict {amount, currency}, amount as a decimal string.
token_units
token_units(input_tokens: int, output_tokens: int, cached_input_tokens: int = 0, reasoning_tokens: int = 0) -> dict[str, int]
Token units following the FinOps rule.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
input_tokens | int | yes | Total input tokens reported by the provider, cached tokens included. | |
output_tokens | int | yes | Total output tokens reported by the provider, reasoning tokens included. | |
cached_input_tokens | int | 0 | no | Cached input tokens, already counted in input_tokens (default 0); more than input_tokens raises ValueError. |
reasoning_tokens | int | 0 | no | Reasoning tokens, already counted in output_tokens (default 0); more than output_tokens raises ValueError. |
Returns: dict[str, int]. Dict {input_tokens, output_tokens}, plus cached_input_tokens and reasoning_tokens when not zero.
Raises: ValueError.
usage_event
usage_event(usage_type: str, provider: str, units: dict[str, Any], tenant_id: str, region: str = 'global', agent_id: str | None = None, session_id: str | None = None, task_id: str | None = None, run_id: str | None = None, model_id: str | None = None, source: str = 'runtime', pricing: dict[str, Any] | None = None, cost: dict[str, Any] | None = None, **extra: Any) -> dict[str, Any]
Build a Usage Event document (cost is computed by the server when not given).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
usage_type | str | yes | Kind of usage, for example llm. | |
provider | str | yes | Provider that served the usage, for example openai. | |
units | dict[str, Any] | yes | Consumed units, for tokens the dict of token_units. | |
tenant_id | str | yes | Tenant charged with the usage. | |
region | str | 'global' | no | Region of the usage (default global). |
agent_id | str | None | None | no | Agent that consumed, optional. |
session_id | str | None | None | no | Session the usage belongs to, optional. |
task_id | str | None | None | no | Task the usage belongs to, optional. |
run_id | str | None | None | no | Run the usage belongs to; the run_id key is added only when given. |
model_id | str | None | None | no | Model used, optional. |
source | str | 'runtime' | no | Producer of the event (default runtime). |
pricing | dict[str, Any] | None | None | no | Pricing reference; default {currency: EUR, pricing_version: server, effective_at: now}. |
cost | dict[str, Any] | None | None | no | Cost {estimated, measured, billed}; default all None, the server computes it. |
**extra | Any | no | Extra fields merged into the request body. |
Returns: dict[str, Any]. Usage Event dict with schema_version 1.0, a new event_id (ue- prefix) and occurred_at now in UTC; extra keyword arguments are merged in.