# Cost Explorer API

> Call the Cost Explorer API: base URL, authentication, a first request, and every operation.

The Cost Explorer API is a JSON API over HTTPS. Estimated costs and usage of your projects, with forecasts.

## Base URL

```
https://cost-explorer.public.global.vexxhost.net
```

## Authentication

Send a token from [Identity](/identity/authentication) in the `Authorization: Bearer` or `X-Auth-Token` header with every request. See [Make API requests](/developer/api) for status codes and retries.

## Make your first request

Report what your project spent in September:

```sh
curl --request POST https://cost-explorer.public.global.vexxhost.net/v1/cost_reports \
  --header "X-Auth-Token: $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "time_period": {"start": "2026-09-01T00:00:00Z", "end": "2026-10-01T00:00:00Z"},
    "granularity": "monthly",
    "metrics": ["cost"],
    "group_by": []
  }'
```

```json
{
  "as_of": "2026-10-07T15:12:40Z",
  "currency": "USD",
  "pricing_version": "legacy-usd-21c6b51",
  "group_definitions": [],
  "regions": [{"name": "ca-ymq-1", "data_through": "2026-10-07T14:00:00Z"}],
  "results_by_time": [
    {
      "time_period": {"start": "2026-09-01T00:00:00Z", "end": "2026-10-01T00:00:00Z"},
      "estimated": true,
      "total": {"cost": {"amount": "1084.296000000000", "unit": "USD"}},
      "groups": []
    }
  ]
}
```

Reports and forecasts are computed for each request and are not stored, so both operations are
`POST` requests that return their result directly.

## Errors

Errors use the [problem details](https://www.rfc-editor.org/rfc/rfc9457) format, `application/problem+json`. `detail` says what went wrong, and a validation error lists each problem in `errors` with the `location` of the field:

```json
{
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "validation failed",
  "errors": [
    {
      "location": "body",
      "message": "expected required property time_period to be present",
      "value": {}
    }
  ]
}
```

Every response carries an `X-Request-ID` header. Include it when you contact support about a request.

When the service is busy it answers `429 Too Many Requests` with a `Retry-After` header. Wait that many seconds, then send the request again.

## Operations

| Method | Path                                                                           | Description                       |
| ------ | ------------------------------------------------------------------------------ | --------------------------------- |
| `POST` | [`/v1/cost_forecasts`](/cost-explorer/api/cost-forecasts/create-cost-forecast) | Calculate a cost forecast         |
| `POST` | [`/v1/cost_reports`](/cost-explorer/api/cost-reports/create-cost-report)       | Calculate a cost and usage report |

## OpenAPI schema

Download the schema as [JSON](/cost-explorer/openapi.json) or [YAML](/cost-explorer/openapi.yaml) to generate a client or import the API into a tool such as Postman.