resources/finops.ts

Source: sdks/typescript/packages/sdk/src/resources/finops.ts. Back to the TypeScript SDK reference index.

note

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.

Interface TokenUnits

Token units of a Usage Event; cached tokens are part of the input and reasoning tokens part of the output.

Fields:

Name	Type	Required	Description
input_tokens	number	yes	Total input tokens reported by the provider.
output_tokens	number	yes	Total output tokens reported by the provider.
cached_input_tokens	number	no	Input tokens served from the cache, included in input_tokens.
reasoning_tokens	number	no	Explicit reasoning tokens, at least 0; overrides the reserve of reasoning_effort.

Type alias ReconciliationSource

Format of a bill import: openai, anthropic, aws_cur, azure, gcp or generic_csv.

Definition: "openai" \| "anthropic" \| "aws_cur" \| "azure" \| "gcp" \| "generic_csv".

Interface FinOpsSettings

FinOps settings of the tenant: currency, monthly budget, variance threshold and reservation lifetime.

Fields:

Name	Type	Required	Description
currency	string	yes	ISO 4217 currency code, for example EUR.
monthly_budget	string | null	yes	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	string	yes	Variance between measured and billed cost, in percent, above which a variance alert is raised (default 10).
reservation_ttl_seconds	number	yes	Default lifetime of a quota reservation in seconds, greater than 0 (default 900).

Type alias SummaryGroupBy

Grouping of FinOpsResource.summary: tenant, project, agent, model, provider, usage_type or day.

Definition: "tenant" \| "project" \| "agent" \| "model" \| "provider" \| "usage_type" \| "day".

Class FinOpsResource

FinOps. Cost management of AI usage: price cards, usage events, estimates, quotas and reservations, GPU cost allocation, billing reconciliation and alerts.

Resource

Attributes:

Name	Type	Required	Description
alerts	Alerts	yes	FinOps alerts (GET /v1/finops/alerts).
allocationPolicies	AllocationPolicies	yes	Cost allocation policies: list and create on /v1/finops/allocation-policies.
fxRates	FxRates	yes	Exchange rates: list and put on /v1/finops/fx-rates.
gpu	Gpu	yes	GPU usage: ingestSamples and allocation on /v1/finops/gpu.
priceCards	PriceCards	yes	Price cards: list, create, get and retire on /v1/finops/price-cards.
reconciliation	Reconciliation	yes	Reconciliation with provider bills: imports, run and report (/v1/finops/reconciliation).
settings	Settings	yes	FinOps settings of the tenant: get and update on /v1/finops/settings.
usage	Usage	yes	Usage Events: ingest, ingestBatch, list and iterate on /v1/finops/usage.

FinOpsResource.checkBudget

checkBudget(query: { agent?: string; project?: string; run?: string } = {}, opts?: CallOptions)

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
query	{ agent?: string; project?: string; run?: string }	{}	no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

FinOpsResource.createMediaPrice

createMediaPrice(body: Doc, opts?: CallOptions)

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
body	Doc		yes	unit (audio_second, image, video_second, gpu_second, storage_gb_month), provider, unit_price (number, at least 0), currency (ISO 4217), source (where the price comes from, required), optional resource (default *, the whole provider) and effective_from (ISO 8601, default now).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

FinOpsResource.estimate

estimate(body: Doc, opts?: CallOptions)

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
body	Doc		yes	The planned call to price.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

FinOpsResource.estimateMediaCost

estimateMediaCost(body: Doc, opts?: CallOptions)

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
body	Doc		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).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

FinOpsResource.mediaPrices

mediaPrices(query: { unit?: string } = {}, opts?: CallOptions)

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
query	{ unit?: string }	{}	no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

FinOpsResource.recordUsage

recordUsage(event: UsageEvent | Doc, opts?: CallOptions)

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	UsageEvent | Doc		yes	Usage Event to record; sending the same event_id twice records it once.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

FinOpsResource.reserve

reserve(body: ReserveBody, opts?: CallOptions)

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
body	ReserveBody		yes	Amount, scope and lifetime of the reservation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

FinOpsResource.summary

summary(query: { group_by?: SummaryGroupBy; from?: string; to?: string } & Query = {}, opts?: CallOptions)

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
query	{ group_by?: SummaryGroupBy; from?: string; to?: string } & Query	{}	no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

Interface QuotaReservation

POST /v1/quotas/reserve, commit and release response; id is the reservation id.

Doc

Fields:

Name	Type	Required	Description
id	string	yes	Id of the reservation, used to commit or release it.
tenant_id	string	yes	Tenant of the agent. Default default.
status	"reserved" | "committed" | "released" | "expired" | string	yes	reserved, committed, released or expired.
amount	{ cost: { amount: string; currency: string }; tokens: number }	yes	Reserved cost (amount and currency) and tokens.
expires_at	string	yes	Date and time (ISO 8601, UTC) after which the item is no longer valid.
quotas	Doc[]	yes	Quotas the reservation counts against.
soft_exceeded	Doc[]	yes	Soft quotas the reservation goes over.

Interface ReserveBody

Body of POST /v1/quotas/reserve: cost, tokens, scope and lifetime of the reservation.

Fields:

Name	Type	Required	Description
cost	string | number	no	Cost to reserve.
tokens	number	no	Tokens to reserve.
scope	Doc	no	What is backed up (clusters, services, data sets), as an object.
ttl_seconds	number	no	Lifetime in seconds. Once it has elapsed, the item expires and is no longer accepted.

Interface CommitBody

Body of QuotasResource.commit: the measured cost and tokens of the reservation.

Fields:

Name	Type	Required	Description
cost	string | number	no	Measured cost to commit.
tokens	number	no	Measured tokens to commit.

Interface WithReservationOptions

Options of QuotasResource.withReservation.

Fields:

Name	Type	Required	Description
commitBody	(result: T) => CommitBody	no	Builds the commit body (measured cost and tokens) from the callback result.
opts	CallOptions	no	Per call options accepted by every SDK method.

Interface QuotaCreate

Body of POST /v1/quotas.

Doc

Fields:

Name	Type	Required	Description
name	string	yes	Name of the quota.
scope_type	"tenant" | "project" | "user" | "agent" | "model" | "provider"	no	What the quota limits: tenant (default), project, agent, user, model or provider.
scope_value	string	no	Identifier of the project, agent, user, model or provider; required unless scope_type is tenant, where it must be null.
period	"request" | "run" | "hour" | "day" | "month"	no	Period of the quota: request, run, hour, day or month.
limit_cost	string | number	no	Cost limit over the period.
limit_tokens	number	no	Token limit over the period.
currency	string	no	ISO 4217 currency code, for example EUR.
enforcement	"hard" | "soft"	no	hard refuses over the limit, soft only reports it.
enabled	boolean	no	Whether the quota is enforced.

Class QuotasResource

FinOps. Cost management of AI usage: price cards, usage events, estimates, quotas and reservations, GPU cost allocation, billing reconciliation and alerts.

Resource

Attributes:

Name	Type	Required	Description
fn	(reservation: QuotaReservation)	yes	Callback of withReservation, run with the reservation.
options	WithReservationOptions<T>	yes	Options of withReservation: commit body builder and per call options.
reserveBody	ReserveBody,	yes	Body of the reservation made by withReservation.

QuotasResource.commit

commit(id: string, body: CommitBody = {}, opts?: CallOptions)

Commit a reservation. Replaces the reserved amount by the measured one on every quota window of the reservation and checks the alert thresholds. A closed reservation answers 409 reservation_closed; an unknown one 404 reservation_not_found. Audited. Requires finops, tenant_admin, agent or developer, and a tenant principal.

Route: /v1/quotas/{reservation_id}/commit (POST).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the reservation returned by POST /v1/quotas/reserve.
body	CommitBody	{}	no	Measured cost and tokens of the call.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

QuotasResource.create

create(body: QuotaCreate, opts?: CallOptions)

Create a quota. Creates a quota of the tenant and answers 201. A cost or token limit is required, and scope_value is required unless scope_type is tenant (422 validation_error). Without currency, the tenant currency applies. Audited. Requires finops or tenant_admin, and a tenant principal.

Route: /v1/quotas (POST).

Name	Type	Default	Required	Description
body	QuotaCreate		yes	The new quota.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

QuotasResource.delete

delete(id: string, opts?: CallOptions)

Delete a quota. Deletes a quota of the tenant and answers 204. Unknown id: 404 quota_not_found. Audited (finops.quota.delete). Requires finops or tenant_admin.

Route: /v1/quotas/{quota_id} (DELETE).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the quota.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

QuotasResource.list

list(params?: ListParams, opts?: CallOptions)

List the quotas. Quotas of the tenant by name, including those mirrored from the LLM projects (llm-project:...). One page only. Requires a reader role and a tenant principal.

Route: /v1/quotas (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

QuotasResource.release

release(id: string, opts?: CallOptions)

Release a reservation. Gives the reserved amount back to every quota window of the reservation without consuming anything (the call failed or was not made). A closed reservation answers 409 reservation_closed; an unknown one 404 reservation_not_found. Audited. Requires finops, tenant_admin, agent or developer, and a tenant principal.

Route: /v1/quotas/{reservation_id}/release (POST).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the reservation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

QuotasResource.replace

replace(id: string, body: Doc, opts?: CallOptions)

Replace a quota. Replaces every field of a quota (same rules as on creation; without currency, the current one is kept). Unknown id: 404 quota_not_found. Audited. Requires finops or tenant_admin, and a tenant principal.

Route: /v1/quotas/{quota_id} (PUT).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the quota.
body	Doc		yes	The complete quota.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

QuotasResource.reserve

reserve(body: ReserveBody, opts?: CallOptions)

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
body	ReserveBody		yes	Amount, scope and lifetime of the reservation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

QuotasResource.usage

usage(query?: Query, opts?: CallOptions)

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
query	Query		no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

Raises: the typed errors of the transport (Errors).

QuotasResource.withReservation

async withReservation(reserveBody: ReserveBody, fn: (reservation: QuotaReservation) = Promise<T>, options: WithReservationOptions<T> = {},): Promise<T>

Reserves quota, runs fn, then commits on success or releases on failure; the callback error is rethrown after the release.

Name	Type	Default	Required	Description
reserveBody	ReserveBody		yes	Cost, tokens, scope and lifetime to reserve.
fn	(reservation: QuotaReservation)	Promise<T>, options: WithReservationOptions<T> = {},	no	Work to run under the reservation.

Returns: Promise<T>. Result of fn.

Functions

tokenUnits

tokenUnits(input: number, output: number, detail: { cached?: number; reasoning?: number } = {}): TokenUnits

Token units following the FinOps rule: input_tokens already includes the cached tokens and output_tokens already includes the reasoning tokens (provider totals, never added on top).

Name	Type	Default	Required	Description
input	number		yes	Total input tokens.
output	number		yes	Total output tokens.
detail	{ cached?: number; reasoning?: number }	{}	no	Cached and reasoning tokens, each at most its total.

Returns: TokenUnits. The units, cached and reasoning fields only when not zero; throws RangeError when a part exceeds its total.

Raises: RangeError.