## Total cloud spend exploration

### Explore total cloud spend

`get/beta/v1/org/{org_id}/cost-explorer`

Returns total cloud spend over a date range, optionally grouped by service, account, or region. Includes all cost types (not just reservable). Data comes from cloud provider Cost Explorer APIs.

### Path parameters

- `org_id` **string** · uuid **Required**

### Query parameters

- `provider` **string** · enum **Required**  
  Cloud provider (aws, azure, gcp)  
  Example: `aws` Possible values: `aws`, `azure`, `gcp`

- `segment_id` **string** · uuid · nullable **Optional**  
  Optional segment ID to scope results. Defaults to the provider resources segment if not specified.  
  Default: `null`

- `start_date` **string** · date **Required**  
  Start date (YYYY-MM-DD)

- `end_date` **string** · date **Required**  
  End date (YYYY-MM-DD, exclusive)

- `group_by` **string** · enum · nullable **Optional**  
  Dimension to group costs by: 'service', 'account', or 'region'. If omitted, returns total spend without grouping.  
  Default: `null` Possible values: `service`, `account`, `region`, `null`

- `granularity` **string** · enum **Optional**  
  Time granularity: 'daily' or 'monthly' (default 'daily')  
  Default: `daily` Possible values: `daily`, `monthly`

- `metric` **string** · enum **Optional**  
  Cost metric to use. 'amortized' (default): includes upfront costs spread over commitment term. 'unblended' (AWS only): actual charges as they appear on the bill. 'actual' (Azure/GCP only): equivalent to unblended for Azure and GCP.  
  Default: `amortized` Possible values: `amortized`, `unblended`, `actual`

- `top_n` **integer** · min: 1 · nullable **Optional**  
  Return only the top N groups by cost, with remaining groups combined into 'Other'. If omitted, returns all groups.  
  Default: `null`

- `include_discounts_and_credits` **boolean** · Optional  
  Include credits, refunds, and enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements) in the cost data. Default false (shows spend before credits and discounts).  
  Default: `false`

- `include_time_series` **boolean** · Optional  
  Include time-series data points for each group. Default true. Set to false for compact summary-only responses.  
  Default: `true`

- `filter` **object** · nullable **Optional**  
  Pre-query filter applied before grouping. Uses field/op/value with and/or/not combinators. Supported operators: = (equals), != (not equals), in (list of values). Available fields: service, account_id, region, instance_type, instance_family, operating_system, tenancy. Example: {"field": "service", "op": "!=" , "value": "Tax"}

Default: `null`

### Responses

**200 OK**  
```json
{
  "period_start": "text",
  "period_end": "text",
  "total_cost": 1,
  "groups": [
    {
      "name": "text",
      "total_cost": 1,
      "percentage": 1,
      "data": [
        {
          "date": "text",
          "cost": 1
        }
      ]
    }
  ]
}
```

**400 Bad request**

**401 Unauthorized**

**403 Forbidden**

**404 Not found**

**405 Method not allowed**

**409 Conflict**

**422 Unprocessable Content**

**500 Internal server error**

**default** Default error response

---

### Get available cost-explorer filter fields and values

`get/beta/v1/org/{org_id}/cost-explorer/filters`

Returns the valid filter fields and their possible values for building cost-explorer filter parameters. Field names in the response can be used directly as the 'field' value in filter expressions.

### Path parameters

- `org_id` **string** · uuid **Required**

### Query parameters

- `provider` **string** · enum **Required**  
  Cloud provider (aws, azure, gcp)  
  Example: `aws` Possible values: `aws`, `azure`, `gcp`

### Responses

**200 OK**  
```json
{
  "service": [
    "text"
  ],
  "account_id": [
    "text"
  ],
  "region": [
    "text"
  ],
  "instance_family": [
    "text"
  ],
  "operating_system": [
    "text"
  ],
  "tenancy": [
    "text"
  ]
}
```