API Reference

CloudExpat REST API for accessing cloud cost and carbon data

Base URL

https://data.cloudexpat.com

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Getting an API Key

Log in to CloudExpat
Go to Settings > API Keys
Click Create API Key

API keys use the format: ce_live_ followed by 32 characters.

GET /v1/costs/summary

Returns cost summary for all connected cloud accounts.

Parameters

Parameter	Type	Default	Description
`period`	string	`month`	`day`, `week`, or `month`
`compare`	string	`previous`	`previous` or `none`
`accountId`	string	—	Filter to specific account

Request

curl "https://data.cloudexpat.com/v1/costs/summary?period=month" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "generatedAt": "2025-12-16T10:30:00.000Z",
  "period": {
    "start": "2025-11-16",
    "end": "2025-12-16",
    "label": "This Month"
  },
  "comparison": {
    "start": "2025-10-16",
    "end": "2025-11-16",
    "label": "Last Month"
  },
  "accounts": [
    {
      "accountId": "abc-123",
      "accountName": "Production",
      "provider": "aws",
      "externalId": "123456789012",
      "costs": {
        "current": 1234.56,
        "previous": 1100.00,
        "delta": {
          "absolute": 134.56,
          "percentage": 12.23
        },
        "currency": "USD",
        "isEstimate": false
      },
      "byService": [
        { "service": "Amazon EC2", "cost": 800.00, "percentage": 64.8 },
        { "service": "Amazon S3", "cost": 234.56, "percentage": 19.0 }
      ]
    }
  ],
  "totals": {
    "current": 1234.56,
    "previous": 1100.00,
    "delta": {
      "absolute": 134.56,
      "percentage": 12.23
    },
    "currency": "USD"
  }
}

GET /v1/carbon/summary

Returns carbon emissions data for all connected cloud accounts.

Parameters

Parameter	Type	Default	Description
`period`	string	`month`	`day`, `week`, or `month`
`compare`	string	`previous`	`previous` or `none`
`accountId`	string	—	Filter to specific account

Request

curl "https://data.cloudexpat.com/v1/carbon/summary" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "generatedAt": "2025-12-16T10:30:00.000Z",
  "period": {
    "start": "2025-11-16",
    "end": "2025-12-16",
    "label": "This Month"
  },
  "accounts": [
    {
      "accountId": "abc-123",
      "accountName": "Production",
      "provider": "aws",
      "emissions": {
        "current": 45.67,
        "previous": 42.00,
        "delta": {
          "absolute": 3.67,
          "percentage": 8.74
        },
        "unit": "kgCO2e",
        "isEstimate": false,
        "dataSource": "aws_carbon_footprint"
      }
    }
  ],
  "totals": {
    "current": 45.67,
    "previous": 42.00,
    "delta": {
      "absolute": 3.67,
      "percentage": 8.74
    },
    "unit": "kgCO2e"
  }
}

GET /v1/report

Combined cost and carbon report. Supports JSON and Markdown formats.

Parameters

Parameter	Type	Default	Description
`format`	string	`json`	`json` or `markdown`
`period`	string	`month`	`day`, `week`, or `month`
`include_carbon`	boolean	`true`	Include carbon emissions
`accountId`	string	—	Filter to specific account
`max_accounts`	number	`10`	Max accounts to include (up to 20)
`max_services`	number	`5`	Max services per account (up to 10)

Request (JSON)

curl "https://data.cloudexpat.com/v1/report?format=json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Request (Markdown)

curl "https://data.cloudexpat.com/v1/report?format=markdown" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (JSON)

{
  "costs": { /* CostSummaryResponse */ },
  "carbon": { /* CarbonSummaryResponse */ },
  "resources": { /* ResourceSummary - when no cost data */ },
  "dataQuality": {
    "status": "actual",
    "message": "Cost data retrieved successfully."
  },
  "metadata": {
    "generatedAt": "2025-12-16T10:30:00.000Z",
    "apiVersion": "v1",
    "dashboardUrl": "https://app.cloudexpat.com/dashboard"
  }
}

Response (Markdown)

Returns plain text Markdown suitable for PR comments. See GitHub Action guide for example output.

Data Quality

The API includes data quality indicators in responses:

Status	Description
`actual`	Full cost data from Cost Explorer/Cost Management
`estimated`	Pricing estimates when detailed data unavailable
`no_data`	No cost data available (new account or not configured)

When status is no_data, a resources field provides detected cloud resources as a fallback.

Error Handling

Status	Description
`200`	Success
`401`	Invalid or missing API key
`429`	Rate limit exceeded
`500`	Server error

Error Response

{
  "error": "INVALID_API_KEY",
  "message": "The provided API key is invalid or expired",
  "code": "INVALID_API_KEY"
}

Error Codes

Code	Description
`INVALID_API_KEY`	API key not found or revoked
`INVALID_API_KEY_FORMAT`	Key doesn’t match expected format
`RATE_LIMIT_EXCEEDED`	Too many requests
`INTERNAL_ERROR`	Server-side error

Rate Limits

100 requests per hour per API key
Rate limit headers included in responses:
- X-RateLimit-Limit: Max requests per window
- X-RateLimit-Remaining: Requests remaining
- X-RateLimit-Reset: Unix timestamp when window resets

Multi-Cloud Support

Supported providers: aws, azure, gcp

All endpoints automatically aggregate data from all connected cloud accounts. Use the accountId parameter to filter to a specific account.

SDKs & Examples

cURL

# Get monthly cost summary
curl "https://data.cloudexpat.com/v1/costs/summary" \
  -H "Authorization: Bearer ce_live_xxxxx"

# Get weekly report as Markdown
curl "https://data.cloudexpat.com/v1/report?format=markdown&period=week" \
  -H "Authorization: Bearer ce_live_xxxxx"

JavaScript/Node.js

const response = await fetch(
  'https://data.cloudexpat.com/v1/costs/summary',
  {
    headers: {
      'Authorization': `Bearer ${process.env.CLOUDEXPAT_API_KEY}`
    }
  }
);
const data = await response.json();
console.log(`Total cost: $${data.totals.current}`);

Python

import requests

response = requests.get(
    'https://data.cloudexpat.com/v1/costs/summary',
    headers={'Authorization': f'Bearer {api_key}'}
)
data = response.json()
print(f"Total cost: ${data['totals']['current']}")