Reports & Analytics

Cost flow Sankey, anomaly detection, trends, snapshots, team and tag attribution, budgets, and unit economics — all from a single cost_records fact table.

Track cloud costs, savings from automated scheduling, and monitor resource utilization across all your connected accounts.

Dashboard Summary

GET/reports/summary

Get an overall cost and savings summary for the current period.

Response · json

{
"data": {
  "totalCostUSD": 12450.50,
  "totalSavingsUSD": 3280.75,
  "resourceCount": 156,
  "period": "2025-01"
}
}

Cost Flow (Sankey)

A configurable Sankey view of how cost flows across providers, accounts, regions, resource types, services, purchase types, and teams. The default flow is Provider -> Account -> ResourceType -> Team and can be reshaped to any ordered sequence of dimensions; the URL is shareable so a drilldown can be sent in chat.

Supported dimensions

provider
cloud_account_id
region
resource_type
service_name
purchase_type
team_id
resource_uid (drilldown only)

Overlays

Savings overlay — highlights links carrying idle, orphan, or right-sizing savings opportunities surfaced by Recommendations.
Unattributed overlay — surfaces cost flowing to resources missing team or tag attribution. Use this to find gaps in Smart Tags coverage.

GET/reports/costs/breakdown

Generic GROUP BY on cost_records. Reusable for the Sankey, treemaps, custom dashboards, anything future.

Query parameters:

dims — comma-separated dimension list, in order. Allowlisted to the dimensions above.
from / to — ISO 8601 date range.
filter[dim]=value — repeatable, scopes the breakdown.

Example · bash

curl "https://zopnight.com/api/reports/costs/breakdown?dims=provider,cloud_account_id,resource_type,team_id&from=2026-04-01&to=2026-04-27" \
-H "Authorization: Bearer <token>"

Response · json

{
"data": {
  "nodes": [
    { "id": "aws", "dim": "provider" },
    { "id": "aws|123456789012", "dim": "cloud_account_id", "label": "Production AWS" },
    { "id": "aws|123456789012|aws-ec2", "dim": "resource_type" },
    { "id": "aws|123456789012|aws-ec2|team_platform", "dim": "team_id", "label": "Platform" }
  ],
  "links": [
    { "source": "aws", "target": "aws|123456789012", "valueUSD": 4200.50 },
    { "source": "aws|123456789012", "target": "aws|123456789012|aws-ec2", "valueUSD": 2800.00 },
    { "source": "aws|123456789012|aws-ec2", "target": "aws|123456789012|aws-ec2|team_platform", "valueUSD": 1900.50 }
  ],
  "totalUSD": 4200.50
}
}

Export

The Sankey supports CSV and PNG export. CSV exports the underlying flow rows (source, target, dimension, value); PNG exports the rendered diagram with the same URL-encoded state.

Cost Anomaly Detection

ZopNight detects unusual cost spikes across five dimensions (org, cloud account, resource group, resource, team) using percentage deviation and z-score analysis, with 14-day root-cause attribution. See Cost Anomaly Detection for the full feature, including detection algorithm, notification cooldown, dedup, and the two-level drawer.

GET/reports/anomalies

List anomaly records for a window. Suppressed records map to severity info.

Cost Trends

GET/reports/trends

Get daily cost and savings trend data for charts and dashboards.

Response · json

{
"data": {
  "items": [
    {
      "date": "2025-01-15",
      "costUSD": 425.30,
      "savingsUSD": 112.50
    },
    {
      "date": "2025-01-16",
      "costUSD": 418.20,
      "savingsUSD": 119.80
    }
  ]
}
}

GET/reports/cost-history

Long-range cost history for charts that span multiple months. Accepts granularity (daily, weekly, monthly) and a date range.

GET/reports/metrics

Aggregate utilization metrics across the org (CPU, memory, disk) used by the dashboard hero. Backed by the discoverer's metrics enrichment.

GET/reports/resources/metrics

Per-resource utilization metrics over a window (CPU, memory, network). Used by the resource detail drawer.

GET/reports/resources/activity

Per-resource activity timeline (state transitions, scheduler events, action submissions, configuration changes).

POST/reports/export

Export a cost report as CSV or JSON. Accepts the same dimensions and filters as the report endpoints; returns a download URL.

Request · bash

curl -X POST https://zopnight.com/api/reports/export \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "report": "costs/breakdown",
  "format": "csv",
  "dimensions": ["provider", "team_id"],
  "from": "2026-04-01",
  "to": "2026-04-30"
}'

Response · json

{
"data": {
  "downloadURL": "https://zopnight.com/exports/cost-2026-04.csv",
  "expiresAt": "2026-04-30T01:00:00Z"
}
}

Resource Costs

GET/reports/costs/resources

Get per-resource cost breakdown.

Example · bash

curl "https://zopnight.com/api/reports/costs/resources?page=1&limit=20" \
-H "Authorization: Bearer <token>"

Provider Summary

GET/reports/providers/summary

Get cost and resource count breakdown by cloud provider.

Response · json

{
"data": {
  "aws": {
    "count": 85,
    "costUSD": 7200.00
  },
  "gcp": {
    "count": 42,
    "costUSD": 3150.50
  },
  "azure": {
    "count": 29,
    "costUSD": 2100.00
  }
}
}

Resource Summary

GET/reports/resources/summary

Get resource count hierarchy grouped by provider and cloud account.

Response · json

{
"data": {
  "providers": [
    {
      "name": "aws",
      "total": 85,
      "accounts": [
        {
          "id": "ca_001",
          "name": "Production AWS",
          "total": 60,
          "byType": {
            "aws-ec2": 25,
            "aws-rds": 8,
            "aws-eks": 3
          }
        }
      ]
    }
  ],
  "total": 156
}
}

Cost Attribution (Showback)

Slice cost by team (derived from resource group ownership) or by tag (cloud tags, GCP labels, Azure tags, and accepted smart tags). Both dimensions are computed from the same daily billing rollup, so team and tag totals always reconcile to the provider total.

By Team

GET/reports/teams

List cost per team for the selected period.

Response · json

{
"data": [
  {
    "teamID": "team_001",
    "teamName": "Platform",
    "costUSD": 4200.50,
    "resourceCount": 42,
    "percentOfTotal": 33.7
  }
]
}

GET/reports/teams/{teamID}

Get a per-team breakdown by provider and resource type.

GET/reports/teams/{teamID}/resources

List resources attributed to a team with their individual cost.

GET/reports/teams/trends

Daily/weekly/monthly trend series for all teams.

By Tag

GET/reports/tags

List tag keys that have attributed cost (cloud tags, GCP labels, Azure tags, accepted smart tags).

Response · json

{
"data": [
  {
    "tagKey": "Environment",
    "coverage": {
      "tagged": 128,
      "untagged": 18
    },
    "costUSD": 12450.50
  }
]
}

GET/reports/tags/{tagKey}

List tag values for a given key and their attributed cost.

GET/reports/tags/{tagKey}/values/{tagValue}/resources

List resources that carry a given tag value with individual cost.

GET/reports/tags/trends

Daily/weekly/monthly trend series filtered by tag key / value / provider / type.

Monthly Snapshots

GET/reports/snapshots

Get historical monthly report snapshots.

Response · json

{
"data": [
  {
    "id": "snap_001",
    "period": "2025-01",
    "totalCostUSD": 12450.50,
    "totalSavingsUSD": 3280.75,
    "resourceCount": 156,
    "createdAt": "2025-02-01T00:00:00Z"
  },
  {
    "id": "snap_002",
    "period": "2024-12",
    "totalCostUSD": 13100.00,
    "totalSavingsUSD": 2900.00,
    "resourceCount": 148,
    "createdAt": "2025-01-01T00:00:00Z"
  }
]
}

Team Budgets

Set monthly cost budgets for teams and track spending against them.

GET/budgets/summary

Get organization-wide budget summary.

Response · json

{
"data": {
  "totalBudgetUSD": 25000.00,
  "totalSpendUSD": 18500.00,
  "percentUsed": 74.0,
  "budgetCount": 5,
  "overBudgetCount": 1
}
}

GET/budgets

List all team budgets.

POST/budgets

Create a team budget.

Request · bash

curl -X POST https://zopnight.com/api/budgets \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "teamName": "Platform Team",
  "resourceGroupID": "grp_abc123",
  "monthlyBudgetUSD": 5000.00,
  "alertThresholdPercent": 80
}'

Response · json

{
"data": {
  "id": "bgt_abc123",
  "teamName": "Platform Team",
  "resourceGroupID": "grp_abc123",
  "monthlyBudgetUSD": 5000.00,
  "alertThresholdPercent": 80,
  "currentSpendUSD": 3200.00,
  "remainingUSD": 1800.00,
  "percentUsed": 64.0,
  "status": "green",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-20T08:00:00Z"
}
}

PUT/budgets/{budgetID}

Update a team budget.

DELETE/budgets/{budgetID}

Delete a team budget.

Budget Status Indicators

Status	Condition	Description
`green`	Spend < alert threshold	Spending is within normal range
`yellow`	Spend >= alert threshold	Spending has crossed the configured alert threshold
`red`	Spend >= 100% of budget	Budget has been exceeded

Scheduler Events

View a log of scheduler-triggered events showing which schedules fired and what actions were taken.

GET/events

List scheduler events.

Response · json

{
"data": [
  {
    "id": "evt_001",
    "scheduleID": "sch_abc123",
    "action": "stop",
    "triggeredAt": "2025-01-20T18:00:00Z",
    "resources": ["i-0abc123def456", "i-0def789abc012"],
    "status": "completed"
  }
]
}

POST/events

Record a scheduler event (primarily used internally by the scheduler service).

Unit Economics

Unit economics correlate spend with business KPIs — cost per order, cost per active user, cost per build minute — so teams can compare cost movement against demand rather than treating spend as a raw line item. Define a metric in /unit-metrics (push, pull, or CSV ingestion), then send values for it and read the resulting series back through Reports.

POST/unit-metric-values/{id}

Push a batch of values for a unit metric. Returns the number of rows ingested. Use for low-volume push integrations and webhooks.

POST/unit-metric-values/{id}/csv

Upload a CSV of historical values. Accepts a single CSV file per request; rows are upserted by timestamp.

POST/unit-metric-values/{id}/test-pull

Run the configured pull integration once and return the rows it produced — without persisting anything. Used by the metric editor's 'Test connection' button.

DELETE/unit-metric-values/{id}

Drop every stored value for a metric. Useful when reseeding from a corrected source.

GET/reports/unit-economics

Time-series of cost-per-unit for a chosen metric, with optional filters (provider, team, tag). Used by the Unit Economics chart on the cost dashboard.