Analyze costs using API

The Domino Cost API returns Cost Center (FinOps) data over a time window: cost allocations, asset costs, and cloud costs. Use the v2 endpoints: they group and filter allocations by Domino fields such as Project and starting user, and by Kubernetes fields such as namespace and pod. The v1 allocation and asset endpoints group only by Domino labels. See the Domino Platform API Reference for every Cost API endpoint and parameter.

Every allocation, asset, and cloud cost endpoint needs the QueryCost permission, which the SysAdmin and GovernanceAdmin roles include.

Choose an endpoint

Endpoint	Returns
`/api/cost/v2/allocation`	Full detail for each group: resource hours, request and usage averages, efficiency, and cost for CPU, GPU, RAM, persistent volumes, network, and load balancers
`/api/cost/v2/allocation/summary`	Cost for each group, with CPU and RAM request and usage averages
`/api/cost/v2/asset`	Cost of nodes, disks, and other infrastructure assets
`/api/cost/v2/cloudCost`	Cloud provider billing data; returns HTTP 501 if cloud costs aren’t available on your deployment

Each endpoint has an /accumulated variant, such as /api/cost/v2/allocation/summary/accumulated, that combines the window into one set of results.

Set the time window

Every endpoint requires window. It accepts:

A duration: 24h is the last 24 hours. 1d is today since midnight UTC, and 7d is today plus the previous six days.
A named period: today, yesterday, week, or lastweek.
A start and end time in UTC, separated by a comma: 2026-11-01T00:00:00Z,2026-11-02T00:00:00Z.

The endpoints without /accumulated return one row per group for each calendar day in the window, each with its own window, so window=7d returns seven rows per group and window=24h usually returns two. The /accumulated endpoints return one row per group for the whole window. To split an accumulated result by day or week, set interval to day or week.

Group results

Set aggregate to the field to group by. To group by more than one field, repeat the parameter, for example aggregate=projectName&aggregate=startingUserUsername. A comma-separated list in a single value returns HTTP 400.

Domino fields: projectId, projectName, projectOwnerId, projectOwnerUsername, organizationName, startingUserId, startingUserUsername, executionId, workloadId, workloadType, workloadEngine, and billingTag.
Kubernetes fields: cluster, node, namespace, controllerKind, pod, container, and service.
Kubernetes labels: label:<label-key>, for example label:app.
Label aliases: department, environment, owner, product, and team group by the labels department, env, owner, app, and team by default.

Each result has a key object with one entry for each aggregate field. Results that don’t fit a group appear under reserved values:

__idle__: node capacity that no workload used.
__unallocated__: workloads that have no value for the grouping field, such as a missing label.
__unmounted__: persistent volumes and load balancers that no workload mounted.

On the allocation endpoints, always set aggregate. Without it, results are grouped by namespace, but each key names the namespace cluster. Values that the allocation endpoints reject:

controller, deployment, daemonset, statefulset, job, cronjob, replicaset, pv, pvc, and storageclass return HTTP 400.
controllerName, services, and asset or cloud cost fields such as name and assetType return HTTP 500. To group by Kubernetes service, use service.

The asset endpoints group by name, category, cluster, project, provider, providerID, account, and service. The cloud cost endpoints group by accountID, category, invoiceEntityID, provider, providerID, and service.

Filter results

Write each filter condition as a field, an operator, and a value in double quotes, such as projectName:"churn-model". Unquoted values and values that contain a double quote return HTTP 400; an escaped double quote (\") returns HTTP 500.

Operator	Matches values that
`:`	Equal the value
`!:`	Don’t equal the value
`<~:`	Start with the value
`!<~:`	Don’t start with the value
`~>:`	End with the value
`!~>:`	Don’t end with the value
`!~:`	Don’t contain the value

The contains operator, ~:, returns HTTP 400. To match any of several values, separate the quoted values with commas: namespace:"domino-compute","domino-platform". Join conditions with + for “and” or | for “or”, and group them with parentheses: (namespace:"domino-compute"|namespace:"domino-platform")+workloadType:"App". Filters accept the Domino fields, the label aliases, label[<label-key>], annotation[<annotation-key>], and the Kubernetes fields cluster, node, namespace, controllerKind, controllerName, pod, container, and services. Filters name Kubernetes services services, not service as in aggregate; service in a filter returns HTTP 500. URL-encode the filter, or + arrives as a space and the request returns HTTP 400. curl --data-urlencode, used in the samples below, encodes it for you. Sharing removes a cost’s own group and spreads the cost across the remaining results, so totals stay the same. Only shareCost adds to the total.

Idle cost: results include idle node capacity as __idle__. Set shareIdle=true to spread it across the other results, or idle=false to leave it out.
Namespaces: shareNamespaces=kube-system,domino-platform shares the cost of the listed namespaces.
Labels: shareLabels=app:aggregator,app:cloud-cost shares the cost of workloads with any of the listed <label-key>:<label-value> pairs. Repeating the parameter uses only its first value.
Fixed amount: shareCost adds a monthly amount, prorated to the window. shareCost=30.42 adds 1.00 to each day.

Shared costs are split in proportion to each result’s cost. shareSplit=weighted is the default; shareSplit=even returns HTTP 500. Don’t set reconcile=false: the summary endpoints return HTTP 500 for it.

Page through results

Set limit to the number of results per page and offset to the number of results to skip. Every page also includes the __idle__ result, unless you set shareIdle=true or idle=false.

API samples

Domino recommends using Service Accounts to access the Domino API. The samples read the access token from $TOKEN, your Domino host name from $DOMAIN, and a Project or user ID from $PROJECT_ID or $USER_ID. Group by projectId or startingUserId to find those IDs.

Total cost for the last 7 days, with idle cost shared among allocations

curl -G "https://$DOMAIN/api/cost/v2/allocation/summary/accumulated" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "window=7d" \
  --data-urlencode "aggregate=cluster" \
  --data-urlencode "shareIdle=true"

Cost by Project and user for the last 7 days

curl -G "https://$DOMAIN/api/cost/v2/allocation/summary/accumulated" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "window=7d" \
  --data-urlencode "aggregate=projectName" \
  --data-urlencode "aggregate=startingUserUsername" \
  --data-urlencode "shareIdle=true"

Cost for one Project yesterday

curl -G "https://$DOMAIN/api/cost/v2/allocation/summary" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "window=yesterday" \
  --data-urlencode "aggregate=projectId" \
  --data-urlencode "aggregate=projectName" \
  --data-urlencode "filter=projectId:\"$PROJECT_ID\""

Daily cost for one user over the last 7 days

curl -G "https://$DOMAIN/api/cost/v2/allocation/summary/accumulated" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "window=7d" \
  --data-urlencode "interval=day" \
  --data-urlencode "aggregate=startingUserUsername" \
  --data-urlencode "shareIdle=true" \
  --data-urlencode "filter=startingUserId:\"$USER_ID\""

Asset costs for yesterday

curl -G "https://$DOMAIN/api/cost/v2/asset" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "window=yesterday"

Cloud costs for the last 7 days, by invoice entity

curl -G "https://$DOMAIN/api/cost/v2/cloudCost/accumulated" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "window=7d" \
  --data-urlencode "aggregate=invoiceEntityID"

Query the v1 endpoints

/api/cost/v1/allocation and /api/cost/v1/allocation/summary group only by Domino labels. Set aggregate to label:dominodatalab.com/<label>, and separate several with commas. <label> is one of project-id, project-name, project-owner-id, project-owner-username, organization-name, starting-user-id, starting-user-username, execution-id, workload-id, workload-type, workload-engine, or billing-tag. Any other value returns HTTP 400. The v1 endpoints pass filter to Kubecost unchanged, so they don’t accept Domino field names, and an unquoted value returns HTTP 500. Use the v2 endpoints for new work.

Next steps

See other ways Domino Cost Center (FinOps) can help you optimize the performance of your Projects while managing cloud expenditures:

Prevent overspending on compute and storage by setting budgets and sending alerts to team members approaching their limits.
Optimize Dataset storage usage to reduce cloud storage costs.

Architecture & deployment

Domino installation

Identity & access

Infrastructure & compute

Platform configuration

Data administration

Operations, monitoring & cost

Security & compliance

Troubleshooting

Analyze costs using API

Choose an endpoint

Set the time window

Group results

Filter results

Page through results

API samples

Total cost for the last 7 days, with idle cost shared among allocations

Cost by Project and user for the last 7 days

Cost for one Project yesterday

Daily cost for one user over the last 7 days

Asset costs for yesterday

Cloud costs for the last 7 days, by invoice entity

Query the v1 endpoints

Next steps

​Choose an endpoint

​Set the time window

​Group results

​Filter results

​Share costs

​Page through results

​API samples

​Total cost for the last 7 days, with idle cost shared among allocations

​Cost by Project and user for the last 7 days

​Cost for one Project yesterday

​Daily cost for one user over the last 7 days

​Asset costs for yesterday

​Cloud costs for the last 7 days, by invoice entity

​Query the v1 endpoints

​Next steps

Choose an endpoint

Set the time window

Group results

Filter results

Share costs

Page through results

API samples

Total cost for the last 7 days, with idle cost shared among allocations

Cost by Project and user for the last 7 days

Cost for one Project yesterday

Daily cost for one user over the last 7 days

Asset costs for yesterday

Cloud costs for the last 7 days, by invoice entity

Query the v1 endpoints

Next steps