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

```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":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp","kubernetes","unknown"]},"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}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## 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","kubernetes","unknown"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostExplorerFilters"}}}},"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":"Get available cost-explorer filter fields and values","description":"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."}}},"components":{"schemas":{"CostExplorerFilters":{"type":"object","properties":{"service":{"type":"array","description":"Available cloud service names","items":{"type":"string"}},"account_id":{"type":"array","description":"Available cloud account IDs","items":{"type":"string"}},"region":{"type":"array","description":"Available cloud regions","items":{"type":"string"}},"instance_family":{"type":"array","description":"Available instance families (AWS only)","items":{"type":"string"}},"operating_system":{"type":"array","description":"Available operating systems (AWS only)","items":{"type":"string"}},"tenancy":{"type":"array","description":"Available tenancy types (AWS only)","items":{"type":"string"}}},"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}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.archera.ai/api-reference/beta-api/cost-explorer-beta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.