# Get cost breakdown

> Returns cost breakdown in different formats: table (paginated), chart (aggregated), csv (export), raw (all records)

Source: https://docs.levelfour.ai/api-reference/costs/get-costs-breakdown


## GET /api/v1/costs/breakdown

Returns cost breakdown in different formats: table (paginated), chart (aggregated), csv (export), raw (all records)

### Authentication

Send `Authorization: Bearer <token>`.

### Parameters

- `format` (query, string, default `table`): Response format: table (paginated UI), chart (aggregated stacked bar), csv (export), raw (all records)
- `period` (query, string, nullable): Period in YYYY-MM format (defaults to current month)
- `provider_id` (query, string, nullable): Filter by provider: aws, gcp, azure, k8s
- `granularity` (query, string, default `daily`): Granularity: 'daily' or 'monthly' (used for chart format)
- `group_by` (query, string, nullable): Grouping dimension for chart format: 'provider' (default) or 'account_id'
- `start` (query, string, nullable): Start date in ISO 8601 format (e.g., 2026-02-01T00:00:00.000Z). Used for chart and table formats
- `end` (query, string, nullable): End date in ISO 8601 format (e.g., 2026-02-01T00:00:00.000Z). Used for chart and table formats
- `page` (query, integer, default `1`): Page number (1-indexed, table format only)
- `page_size` (query, integer, default `10`): Items per page (max 100, table format only)
- `sort_by` (query, string, default `cost`): Sort field: cost, service, region, account_id, change_percentage
- `sort_order` (query, one of `asc`, `desc`, default `desc`): Sort order

### Responses

#### 200: Successful Response

- Variant 1: CostBreakdownResponse
  - `success` (boolean, default `true`)
  - `timestamp` (date-time string)
  - `data` (object, required): Cost breakdown data with pagination
    - `period` (string, required): Period in YYYY-MM format
    - `items` (array of object, required): Service cost breakdown items
      - `service` (string, required): Service name (e.g., Amazon EC2, Cloud SQL)
      - `provider_id` (string, required): Provider identifier: aws, gcp, azure, k8s
      - `environment` (string, nullable): Environment: Production, Staging, etc.
      - `region` (string, nullable): Cloud region
      - `account_id` (string, nullable): Cloud account ID
      - `tag_key` (string, nullable): Tag key if present
      - `tag_value` (string, nullable): Tag value if present
      - `cost` (number, required): Current period cost
      - `previous_cost` (number, nullable): Previous period cost
      - `change_percentage` (number, nullable): Change from previous period
    - `pagination` (object, required): Pagination metadata
      - `total_items` (integer, required): Total number of items across all pages
      - `total_pages` (integer, required): Total number of pages
      - `current_page` (integer, required): Current page number (1-indexed)
      - `page_size` (integer, required): Number of items per page
      - `has_next` (boolean, required): Whether there is a next page
      - `has_previous` (boolean, required): Whether there is a previous page
- Variant 2: CostsBreakdownChartResponse
  - `success` (boolean, default `true`)
  - `timestamp` (date-time string)
  - `data` (object, required): Costs breakdown chart data for stacked bar visualization
    - `granularity` (string, required): Granularity: 'daily' or 'monthly'
    - `start_date` (string, required): Start date in YYYY-MM-DD format
    - `end_date` (string, required): End date in YYYY-MM-DD format
    - `data_points` (array of object, required): Time series data points
      - `date` (string, required): Date in YYYY-MM-DD (daily) or YYYY-MM (monthly) format
      - `aws` (number, default `0`): AWS spending for this period
      - `gcp` (number, default `0`): GCP spending for this period
      - `azure` (number, default `0`): Azure spending for this period
      - `k8s` (number, default `0`): Kubernetes spending for this period
    - `totals` (object, required): Totals by provider for the period
      - `aws` (number, default `0`): Total AWS spending
      - `gcp` (number, default `0`): Total GCP spending
      - `azure` (number, default `0`): Total Azure spending
      - `k8s` (number, default `0`): Total Kubernetes spending
- Variant 3: CostsBreakdownGroupedChartResponse
  - `success` (boolean, default `true`)
  - `timestamp` (date-time string)
  - `data` (object, required): Costs breakdown chart data grouped by account_id
    - `granularity` (string, required): Granularity: 'daily' or 'monthly'
    - `start_date` (string, required): Start date in YYYY-MM-DD format
    - `end_date` (string, required): End date in YYYY-MM-DD format
    - `groups` (array of string, required): Ordered list of group keys (account IDs)
    - `data_points` (array of object, required): Time series data points
      - `date` (string, required): Date in YYYY-MM-DD (daily) or YYYY-MM (monthly) format
      - `groups` (map of string to number, required): Group costs: {'111122223333': 185.30, '123456789012': 245.50}
      - `total` (number, required): Total cost for this date
    - `totals` (map of string to number, required): Total per group for the period
- Variant 4: CostBreakdownRawResponse
  - `success` (boolean, default `true`)
  - `timestamp` (date-time string)
  - `data` (object, required): Cost breakdown raw data without pagination
    - `period` (string, required): Period in YYYY-MM format
    - `items` (array of object, required): All service cost breakdown items (no pagination)
      - `service` (string, required): Service name (e.g., Amazon EC2, Cloud SQL)
      - `provider_id` (string, required): Provider identifier: aws, gcp, azure, k8s
      - `environment` (string, nullable): Environment: Production, Staging, etc.
      - `region` (string, nullable): Cloud region
      - `account_id` (string, nullable): Cloud account ID
      - `tag_key` (string, nullable): Tag key if present
      - `tag_value` (string, nullable): Tag value if present
      - `cost` (number, required): Current period cost
      - `previous_cost` (number, nullable): Previous period cost
      - `change_percentage` (number, nullable): Change from previous period
    - `total_items` (integer, required): Total number of items

#### Errors

- `400`: Bad Request
- `401`: Authentication Error
- `403`: Authorization Error
- `404`: Not Found
- `409`: Conflict
- `422`: Validation Error
- `429`: Rate Limit Exceeded
- `500`: Internal Server Error

Body of `400`, `401`, `403`, `404`, `409`, `422`, `429`, `500`:

- `success` (`false`, required)
- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `details` (any)
- `timestamp` (date-time string, required)