> ## Documentation Index > Fetch the complete documentation index at: https://docs.domino.ai/llms.txt > Use this file to discover all available pages before exploring further. # Analyze costs using API > Query the Domino Cost API for allocation, asset, and cloud costs over a time window, grouped and filtered by Project, user, namespace, or label. The Domino Cost API returns Cost Center 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](https://docs.domino.ai/cloud/reference/api/domino-open-api) for every Cost API endpoint and parameter. > [!NOTE] > > Every allocation, asset, and cloud cost endpoint needs the `QueryCost` permission, which the CloudAdmin and GovernanceAdmin [roles](https://docs.domino.ai/cloud/admin/identity-and-access/manage-users/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:`, 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[]`, `annotation[]`, 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. ## Share costs 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 `:` 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](https://docs.domino.ai/cloud/admin/identity-and-access/manage-users/service-accounts.md) 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 ```shell theme={null} 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 ```shell theme={null} 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 ```shell theme={null} 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 ```shell theme={null} 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 ```shell theme={null} 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 ```shell theme={null} 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/