# Get provider service breakdown

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

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


## GET /api/v1/providers/{provider_id}/costs/breakdown

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

### Authentication

Send `Authorization: Bearer <token>`.

### Parameters

- `provider_id` (path, string, required)
- `format` (query, string, default `table`): Response format: table (paginated UI), chart (aggregated stacked bar), csv (export), raw (all records)
- `start` (query, string, nullable): Start date in ISO 8601 format (e.g., 2026-02-01T00:00:00.000Z). Defaults to first of current month
- `end` (query, string, nullable): End date in ISO 8601 format (e.g., 2026-02-01T00:00:00.000Z). Defaults to today
- `granularity` (query, string, default `daily`): Granularity: 'daily' or 'monthly' (used for chart format)
- `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`): Field to sort by (service, environment, region, account_id, cost, previous_cost, change_percentage)
- `sort_order` (query, one of `asc`, `desc`, default `desc`): Sort order
- `sort_by_date` (query, string, nullable): Sort by a specific date's cost (YYYY-MM-DD for daily, YYYY-MM for monthly). Overrides sort_by.
- `preset` (query, string, nullable): Date preset: '30D', '6M', or '12M' (takes precedence over start/end)
- `service` (query, array of string, nullable): Filter by service(s) - can be repeated for multiple values
- `service_mode` (query, one of `include`, `exclude`, default `include`)
- `environment` (query, array of string, nullable): Filter by environment(s) - can be repeated for multiple values
- `account_id` (query, array of string, nullable): Filter by account ID(s) - can be repeated for multiple values
- `account_id_mode` (query, one of `include`, `exclude`, default `include`)
- `region` (query, array of string, nullable): Filter by region(s) - can be repeated for multiple values
- `region_mode` (query, one of `include`, `exclude`, default `include`)
- `tag_key` (query, array of string, nullable): Filter by tag key(s) - required when group_by=tag
- `tag_key_mode` (query, one of `include`, `exclude`, default `include`)
- `tag_value` (query, array of string, nullable): Filter by tag value(s) - can be repeated for multiple values
- `tag_value_mode` (query, one of `include`, `exclude`, default `include`)
- `virtual_tag_key` (query, array of string, nullable): Virtual tag key, by id or name (case-insensitive). Required when group_by=virtual_tag. One key per request
- `virtual_tag_value` (query, array of string, nullable): Filter by value(s) of virtual_tag_key. __unallocated__ matches cost no config matched
- `virtual_tag_value_mode` (query, one of `include`, `exclude`, default `include`)
- `group_by` (query, array of string, nullable): Group by field(s), for example service, account_id, region, tag or virtual_tag
- `show_cost_as` (query, string, default `unblended`): Cost metric: unblended, blended, amortized, net_unblended, net_amortized, or usage_value (usage priced at list price, an estimate, for the providers that declare it)
- `instance_type` (query, array of string, nullable): Filter by instance type(s)
- `instance_type_mode` (query, one of `include`, `exclude`, default `include`)
- `usage_type` (query, array of string, nullable): Filter by usage type(s)
- `usage_type_mode` (query, one of `include`, `exclude`, default `include`)
- `usage_type_group` (query, array of string, nullable): Filter by usage type group(s)
- `usage_type_group_mode` (query, one of `include`, `exclude`, default `include`)
- `charge_type` (query, array of string, nullable): Filter by charge type(s)
- `charge_type_mode` (query, one of `include`, `exclude`, default `include`)
- `availability_zone` (query, array of string, nullable): Filter by availability zone(s)
- `availability_zone_mode` (query, one of `include`, `exclude`, default `include`)
- `platform` (query, array of string, nullable): Filter by platform(s)
- `platform_mode` (query, one of `include`, `exclude`, default `include`)
- `purchase_option` (query, array of string, nullable): Filter by purchase option(s)
- `purchase_option_mode` (query, one of `include`, `exclude`, default `include`)
- `tenancy` (query, array of string, nullable): Filter by tenancy type(s)
- `tenancy_mode` (query, one of `include`, `exclude`, default `include`)
- `database_engine` (query, array of string, nullable): Filter by database engine(s)
- `database_engine_mode` (query, one of `include`, `exclude`, default `include`)
- `legal_entity` (query, array of string, nullable): Filter by legal entity
- `legal_entity_mode` (query, one of `include`, `exclude`, default `include`)
- `billing_entity` (query, array of string, nullable): Filter by billing entity
- `billing_entity_mode` (query, one of `include`, `exclude`, default `include`)
- `api_operation` (query, array of string, nullable): Filter by API operation(s)
- `api_operation_mode` (query, one of `include`, `exclude`, default `include`)
- `resource` (query, array of string, nullable): Filter by resource ID(s)
- `resource_mode` (query, one of `include`, `exclude`, default `include`)
- `cost_category_key` (query, array of string, nullable): Filter by cost category key(s)
- `cost_category_key_mode` (query, one of `include`, `exclude`, default `include`)
- `cost_category_value` (query, array of string, nullable): Filter by cost category value(s)
- `cost_category_value_mode` (query, one of `include`, `exclude`, default `include`)
- `payer_account` (query, array of string, nullable): Filter by payer account ID(s)
- `payer_account_mode` (query, one of `include`, `exclude`, default `include`)
- `project` (query, array of string, nullable): Filter by project(s), for a connector that collects an inventory. Table format only
- `project_mode` (query, one of `include`, `exclude`, default `include`)
- `sku` (query, array of string, nullable): Filter by billed SKU(s), for a connector provider. Table format only
- `sku_mode` (query, one of `include`, `exclude`, default `include`)
- `search` (query, string, nullable): Case-insensitive substring match across service, account id and name, region, tag key/value, resource id, and usage type. Applies to the table format only.
- `credits` (query, one of `before`, `after`, default `after`): Cost basis for Google Cloud: after credits (default) or before them. AWS stays on its invoiced basis.

### Responses

#### 200: Successful Response

- Variant 1: ProviderServiceBreakdownResponse
  - `success` (boolean, default `true`)
  - `timestamp` (date-time string)
  - `data` (object, required): Provider service breakdown data with pagination
    - `provider_id` (string, required): Provider identifier
    - `provider_name` (string, required): Display name
    - `period` (string, required): Period in YYYY-MM format (legacy, use start_date/end_date)
    - `start_date` (string, required): Start date in YYYY-MM-DD format
    - `end_date` (string, required): End date in YYYY-MM-DD format
    - `total_period_cost` (number, required): Total cost for the period
    - `items` (array of object, required): Service breakdown items
      - `service` (string, nullable): Service name (None if grouped by other fields)
      - `environment` (string, nullable): Environment
      - `region` (string, nullable): Cloud region
      - `account_id` (string, nullable): Cloud account ID
      - `tag_key` (string, nullable): Tag key
      - `tag_value` (string, nullable): Tag value
      - `resource` (string, nullable): Resource id (set when grouped by resource)
      - `sku` (string, nullable): Billed SKU (set when grouped by sku, connector providers only)
      - `project` (string, nullable): Project (set when grouped by project, DigitalOcean only)
      - `usage_type` (string, nullable): Usage type (set when grouped by usage_type)
      - `cost_category` (string, nullable): Cost category value (set when grouped by cost_category)
      - `purchase_type` (string, nullable): Purchase type (set when grouped by purchase_type)
      - `instance_type` (string, nullable): Instance type (set when grouped by instance_type)
      - `charge_type` (string, nullable): Charge type (set when grouped by charge_type)
      - `virtual_tag` (string, nullable): Virtual tag value (set when grouped by virtual_tag). __unallocated__ is cost no config matched
      - `cost` (number, required): Current period cost
      - `previous_cost` (number, nullable): Previous period cost
      - `change_percentage` (number, nullable): Change from previous period
      - `spendings_by_date` (array of object, nullable): Daily spending breakdown for this service
    - `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
    - `totals_by_date` (array of object, nullable): Per-date totals aggregated across all items (all pages)
      - `date` (string, required): Date in YYYY-MM-DD format
      - `value` (number, required): Cost for this date
      - `change_percentage` (number, nullable): Change from previous day
- Variant 2: ProviderServiceCostsBreakdownResponse
  - `success` (boolean, default `true`)
  - `timestamp` (date-time string)
  - `data` (object, required): Provider costs breakdown chart data for stacked bar visualization, grouped by service/account/region/tag
    - `provider_id` (string, required): Provider identifier: aws, gcp, azure, k8s
    - `provider_name` (string, required): Display name
    - `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: ['RDS', 'EC2', 'other']
    - `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: {'RDS': 185.30, 'EC2': 245.50, 'other': 128.65}
      - `total` (number, required): Total cost for this date
    - `totals` (map of string to number, required): Total per group for the period
    - `group_labels` (map of string to string): Display name per group key, for keys that are ids rather than names, such as a Google Cloud project. Keys without a name on file are left out.
- Variant 3: ProviderServiceBreakdownRawResponse
  - `success` (boolean, default `true`)
  - `timestamp` (date-time string)
  - `data` (object, required): Provider service breakdown raw data without pagination
    - `provider_id` (string, required): Provider identifier
    - `provider_name` (string, required): Display name
    - `period` (string, required): Period in YYYY-MM format
    - `start_date` (string, required): Start date in YYYY-MM-DD format
    - `end_date` (string, required): End date in YYYY-MM-DD format
    - `total_period_cost` (number, required): Total cost for the period
    - `items` (array of object, required): All service breakdown items (no pagination)
      - `service` (string, nullable): Service name (None if grouped by other fields)
      - `environment` (string, nullable): Environment
      - `region` (string, nullable): Cloud region
      - `account_id` (string, nullable): Cloud account ID
      - `tag_key` (string, nullable): Tag key
      - `tag_value` (string, nullable): Tag value
      - `resource` (string, nullable): Resource id (set when grouped by resource)
      - `sku` (string, nullable): Billed SKU (set when grouped by sku, connector providers only)
      - `project` (string, nullable): Project (set when grouped by project, DigitalOcean only)
      - `usage_type` (string, nullable): Usage type (set when grouped by usage_type)
      - `cost_category` (string, nullable): Cost category value (set when grouped by cost_category)
      - `purchase_type` (string, nullable): Purchase type (set when grouped by purchase_type)
      - `instance_type` (string, nullable): Instance type (set when grouped by instance_type)
      - `charge_type` (string, nullable): Charge type (set when grouped by charge_type)
      - `virtual_tag` (string, nullable): Virtual tag value (set when grouped by virtual_tag). __unallocated__ is cost no config matched
      - `cost` (number, required): Current period cost
      - `previous_cost` (number, nullable): Previous period cost
      - `change_percentage` (number, nullable): Change from previous period
      - `spendings_by_date` (array of object, nullable): Daily spending breakdown for this service
    - `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)