Cost query API
Pull cost breakdowns, team and tag attribution, unit economics, anomalies, and budgets into your own tools over REST, and see how cost exports are delivered.
The Cost query API returns the same figures as Costs → Reports, Costs → Flow, Costs → Unit Economics, and Costs → Budgets, so you can feed them into finance tooling, dashboards, or chargeback jobs.
Base URL and auth
Paths on this page are relative to your ZopNight API host. Every route is scoped to one organisation, under /orgs/{orgID}.
Send a personal access token in the Authorization: Bearer header. See Authentication for how to create one. Cost reads need a role with report:view; budget reads need budget:view. A role scoped to a list of resources sees costs for those resources only.
Which cost you get
Every route on this page uses the same rule, chosen per resource per day: where a billing row exists for that resource-day (AWS Cost Explorer or CUR 2.0, Azure Cost Management, GCP BigQuery net of credits), it returns billed cost; where none exists, it falls back to rack rate from the provider’s pricing API. Both can appear in the same organisation and the same query. Azure billed cost is amortised, so reservation and savings-plan purchases spread across their term.
Breakdowns and team and tag attribution cover spend that maps to a discovered resource. Billing line items that match no resource (data transfer, taxes, fees, services ZopNight does not discover) are unattributed, so these totals can sit below your invoice.
Cost breakdown
GET /orgs/{orgID}/reports/costs/breakdownReturns the period’s spend split across up to four dimensions. It backs Costs → Flow and is served live, with no snapshot delay.
| Parameter | Type | Description |
|---|---|---|
from | string | Start of the period, for example 2026-08-01. |
to | string | End of the period, for example 2026-08-31. |
dimensions | string | Comma-separated, in column order. For example, provider,cloud_account_id,resource_type,team_id. Other dimensions include region, service_name, purchase_type, and resource_uid. |
providers | string | Optional provider filter. |
resourceTypes | string | Optional resource-type filter. |
comparePrev | boolean | Optional. Compare against the previous period. |
limit | number | Optional. Caps the rows returned. |
curl "$ZOPNIGHT_API/orgs/$ORG_ID/reports/costs/breakdown?from=2026-08-01&to=2026-08-31&dimensions=provider,cloud_account_id,resource_type,team_id" \ -H "Authorization: Bearer $ZOPNIGHT_PAT"Team and tag attribution
See Showback for how teams and tags are attributed.
Teams
GET /orgs/{orgID}/reports/teamsGET /orgs/{orgID}/reports/teams/{teamId}GET /orgs/{orgID}/reports/teams/{teamId}/resourcesGET /orgs/{orgID}/reports/teams/trendsA resource owned by several teams is split equally between them. Resources with no team are tracked separately.
Tags
GET /orgs/{orgID}/reports/tagsGET /orgs/{orgID}/reports/tags/{tagKey}GET /orgs/{orgID}/reports/tags/{tagKey}/values/{tagValue}/resourcesGET /orgs/{orgID}/reports/tags/trendsCloud tags (AWS tags, GCP labels, Azure tags) and accepted Smart Tags each get the resource’s full cost, with no splitting.
| Use | How |
|---|---|
| Page tag keys | /reports/tags accepts page and limit (at most 100). Add includeValues=true to inline each key’s values and their provider and resource-type breakdowns, instead of calling /reports/tags/{tagKey} per key. |
| Tag pairs | /reports/tags?unit=pairs&page=&limit= returns a flat list of key:value pairs sorted by cost. page and limit are both required in this mode. Filter with tagKey, tagValue, provider, resourceType, source (cloud, auto, inherited, mixed), and search; sort with sortBy (cost, savings, resourceCount, name). |
| Trends for several tags | /reports/tags/trends takes repeated tagKey and tagValue parameters, paired by position, and returns one series per pair. |
| Keys or values with a slash | Encode them as b64. followed by the base64url of the raw value when they appear in the path. |
Unit economics
GET /orgs/{orgID}/reports/unit-economicsReturns cost per business unit (per order, per active user, per 1,000 requests) for one unit metric. Each point carries date, cost_usd, metric_value, and cost_per_unit; buckets with a zero denominator are skipped.
| Parameter | Type | Description |
|---|---|---|
metric_id | string | The unit metric. |
from | string | Start of the period. |
to | string | End of the period. |
granularity | string | Bucket size. One of daily, weekly, monthly. |
team_id | string | Optional. Scope the cost to one team. |
tag_key | string | Optional. With tag_value, scope the cost to one tag. |
tag_value | string | Optional. The tag value to pair with tag_key. |
Send denominator values
POST /orgs/{orgID}/unit-metric-values/{id}Takes a JSON array of {date, value} objects from your pipeline.
POST /orgs/{orgID}/unit-metric-values/{id}/csvTakes a CSV upload, up to 1 MB and 5,000 rows.
You can also register an HTTPS endpoint for ZopNight to pull from once a day. Re-sending a date overwrites its value.
Anomaly detection
GET /orgs/{orgID}/reports/anomaliesReturns the anomalies detected in the period, paginated. Detection compares each day against the 7-day rolling average across seven dimensions: org, cloud account, resource type, resource group, resource, team, and Azure resource group or tenant. It runs once a day at 20:55 UTC and ignores series with fewer than 4 data points or under $1 a day. See Cost anomalies for the detection method and severity bands.
| Parameter | Type | Description |
|---|---|---|
from | string | Start of the period. |
to | string | End of the period. |
Budgets
GET /orgs/{orgID}/budgetsReturns every budget with its limit and alert threshold.
| Parameter | Type | Description |
|---|---|---|
spend | boolean | Set spend=false to skip the spend calculation. Default true. |
GET /orgs/{orgID}/budgets/entities/{cloud-accounts|resources|resource-groups}Returns the cloud accounts, resources, or resource groups you can budget, paginated, filtered with status, search, page, and limit.
GET /orgs/{orgID}/budgets/spend/{cloud-accounts|resources|resource-groups}Returns live month-to-date spend for each budgeted entity.
A budget targets one cloud account, resource, resource group, or connected AI provider, and is tracked per team. Each budget has one alert threshold, and its status is green (on track), yellow (at threshold), or red (over budget). Spend is computed live on every read, so a budget update takes effect on the next query. Create and edit budgets under Costs → Budgets.
Export
Exports run in the background, so a large report never blocks the page:
- Cost reports export from Costs → Reports as CSV, covering the visible period, dimensions, and filters.
- Recommendations export as an Excel workbook: an executive summary sheet plus one row per recommendation, honouring the active filters.
When an export is ready, the page shows a short-lived signed download link. Long jobs also email the link, and an Export ready notification can post it to your channels.