> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-cloud-costs.md).

# Query AWS Cloud Costs

Query AWS Cost and Usage Report line items and chart cloud costs with gcQL.

Query AWS Cost and Usage Report (CUR) data collected by your AWS integration. These endpoints are available on supported AWS BYOC backends. Unsupported environments return HTTP `501`.

### Endpoints

| Operation              | Endpoint                                   |
| ---------------------- | ------------------------------------------ |
| Search cost line items | **POST** `/api/aws-cur/search`             |
| Query costs over time  | **POST** `/api/aws-cur/search-time-series` |

### Authentication

Send an [API key](https://docs.groundcover.com/administer/api-keys.md) in `Authorization: Bearer <YOUR_API_KEY>` and select the backend with `X-Backend-Id: <YOUR_BACKEND_ID>`.

### Request Body

| Field            | Type   | Description                                                                |
| ---------------- | ------ | -------------------------------------------------------------------------- |
| `start`, `end`   | string | Time range in RFC3339 format.                                              |
| `query`          | string | gcQL query over cost line items.                                           |
| `pipeline`       | object | Alternative structured query. Supply exactly one of `query` or `pipeline`. |
| `sources`        | array  | Optional structured scope conditions.                                      |
| `filters`        | string | Optional additional filters.                                               |
| `bucketDuration` | string | Time-series interval. Optional; defaults to one day (`24h`).               |
| `valueField`     | string | Numeric result alias to chart.                                             |
| `fillValue`      | number | Optional replacement for empty buckets; defaults to `null`.                |

Unlike APM and ingestion measurements, cost queries do not require a signal or pipeline-stage filter. `_time` refers to the usage start time of each cost line item.

### Example: Cost by AWS Product

```bash
curl --request POST 'https://api.groundcover.com/api/aws-cur/search' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2026-10-01T00:00:00Z",
    "end": "2026-10-28T00:00:00Z",
    "query": "* | stats by (product_code, line_item_currency_code) sum(unblended_cost) as cost | sort by (cost desc) | limit 20"
  }'
```

The response contains `data` rows and `valueFieldHints` listing numeric columns. For example:

```json
{
  "data": [{"product_code": "AmazonEC2", "line_item_currency_code": "USD", "cost": 125.5}],
  "valueFieldHints": ["cost"]
}
```

The amounts above are illustrative. Available cost measures include `unblended_cost`, `net_unblended_cost`, `amortized_cost`, and `net_amortized_cost`. Group by currency when the selection may contain different currencies. Useful dimensions include `region`, `usage_account_id`, `resource_id`, `operation`, and `integration_name`.

### Example: Daily Cost

```bash
curl --request POST 'https://api.groundcover.com/api/aws-cur/search-time-series' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2026-10-01T00:00:00Z",
    "end": "2026-10-28T00:00:00Z",
    "query": "product_code:AmazonEC2 | stats by (line_item_currency_code) sum(unblended_cost) as cost",
    "bucketDuration": "24h",
    "valueField": "cost"
  }'
```

The response is an array of series containing `metric` labels and `velocity` timestamp/value points. See [Time-Series Queries](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/time-series-queries.md).

### Time Range and Report Granularity

Cost reports may arrive later than the usage they describe. Empty recent buckets do not necessarily mean zero cost, so leave `fillValue` unset when you want to preserve missing data.

The API includes only report granularities that fit the requested bucket: buckets below one day include hourly reports; buckets from one day to less than 28 days include hourly and daily reports; larger buckets also include monthly reports. Unknown granularities are excluded. For tabular searches, the whole requested window determines this selection. Do not ingest overlapping exports of the same usage at multiple granularities if you intend to sum them together.

### Errors

Malformed requests, invalid gcQL, or supplying both `query` and `pipeline` return HTTP `400`. Unsupported environments return `501` with the message `This data isn't available in this environment`. Backend query failures return `500`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-cloud-costs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
