# Usage and unit economics by usage type

> Returns spend, billable quantity, unit, and derived cost per unit grouped by usage type.

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


## GET /api/v1/costs/usage

Returns spend, billable quantity, unit, and derived cost per unit grouped by usage type.

### Authentication

Send `Authorization: Bearer <token>`.

### Parameters

- `provider` (query, string, default `aws`)
- `start` (query, string, nullable)
- `end` (query, string, nullable)
- `service` (query, array of string, nullable): Google Cloud only: limit to these services
- `family` (query, one of `bigquery`, `network`, `compute`, `other`, nullable): Google Cloud only: limit to one SKU family and return its categories
- `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

- `success` (boolean, default `true`)
- `timestamp` (date-time string)
- `data` (object, required)
  - `items` (array of object, required): Usage types ranked by cost
    - `usage_type` (string, required): Usage type code, or the SKU description for Google Cloud
    - `cost` (number, required): Cost for this usage type
    - `usage_amount` (number, nullable): Billable quantity, in pricing units for Google Cloud. Null when none was reported.
    - `unit` (string, nullable): Pricing unit (GB-Month, Hrs, Requests, gibibyte month)
    - `cost_per_unit` (number, nullable): Derived cost per unit, null when quantity is zero or the rows mix units
    - `service` (string, nullable): Service billing this SKU. Google Cloud only.
    - `services` (array of string, nullable): Every service billing this SKU. Google Cloud only.
    - `family` (string, nullable): bigquery, network, compute or other. Google Cloud only.
    - `category` (string, nullable): Category within the family. Google Cloud only.
    - `sku_id` (string, nullable): Google Cloud SKU id
    - `gross_cost` (number, nullable): Cost before credits. Google Cloud only.
  - `total_cost` (number, required): Total cost across all usage types
  - `categories` (array of object, nullable): Cost by category. Google Cloud only.
    - `category` (string, required): Category within the requested family
    - `cost` (number, required): Cost in the category
    - `usage_amount` (number, nullable): Quantity, when every SKU in the category shares a unit
    - `unit` (string, nullable): The shared pricing unit
  - `credits` (one of `before`, `after`, nullable): Cost basis applied: after or before Google Cloud credits

#### 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)