Cost Explorer (Beta)

Total cloud spend exploration

Explore total cloud spend

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.

{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Cost Explorer (Beta)","description":"Total cloud spend exploration"}],"paths":{"/beta/v1/org/{org_id}/cost-explorer":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"segment_id","description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false},{"in":"query","name":"start_date","description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date (YYYY-MM-DD, exclusive)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"group_by","description":"Dimension to group costs by: 'service', 'account', or 'region'. If omitted, returns total spend without grouping.","schema":{"default":null,"type":"string","enum":["service","account","region",null],"nullable":true},"required":false},{"in":"query","name":"granularity","description":"Time granularity: 'daily' or 'monthly' (default 'daily')","schema":{"default":"daily","type":"string","enum":["daily","monthly"]},"required":false},{"in":"query","name":"metric","description":"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.","schema":{"default":"amortized","type":"string","enum":["amortized","unblended","actual"]},"required":false},{"in":"query","name":"top_n","description":"Return only the top N groups by cost, with remaining groups combined into 'Other'. If omitted, returns all groups.","schema":{"type":"integer","default":null,"minimum":1,"nullable":true},"required":false},{"in":"query","name":"include_discounts_and_credits","description":"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).","schema":{"type":"boolean","default":false},"required":false},{"in":"query","name":"include_time_series","description":"Include time-series data points for each group. Default true. Set to false for compact summary-only responses.","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"filter","description":"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\"}","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostExplorerResponse"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Cost Explorer (Beta)"],"summary":"Explore total cloud spend","description":"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."}}},"components":{"schemas":{"CostExplorerResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"total_cost":{"type":"number","description":"Total cost across all groups over the effective date range. Headline 'cost' — the answer to 'what did I spend.' Sum of groups[*].total_cost."},"groups":{"type":"array","description":"Cost groups, sorted by total spend descending","items":{"$ref":"#/components/schemas/CostExplorerGroup"}}},"additionalProperties":false},"CostExplorerGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (e.g. service name, account ID, region)"},"total_cost":{"type":"number","description":"Total cost for this group over the entire period"},"percentage":{"type":"number","description":"This group's share of total spend (0-1)"},"data":{"type":"array","default":null,"description":"Time-series data points for this group. Only included when include_time_series=true.","items":{"$ref":"#/components/schemas/CostExplorerDataPoint"},"nullable":true}},"additionalProperties":false},"CostExplorerDataPoint":{"type":"object","properties":{"date":{"type":"string","description":"Date or month label for this data point"},"cost":{"type":"number","description":"Cost for this period"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}}}.

## Get available cost-explorer filter fields and values

> 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.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Cost Explorer (Beta)","description":"Total cloud spend exploration"}],"paths":{"/beta/v1/org/{org_id}/cost-explorer/filters":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostExplorerFilters"}}}}}}}}