# Tag allocation coverage

> Returns showback coverage for a tag key: total, tagged, untagged, coverage percentage, and a per-value breakdown.

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


## GET /api/v1/costs/allocation

Returns showback coverage for a tag key: total, tagged, untagged, coverage percentage, and a per-value breakdown.

### Authentication

Send `Authorization: Bearer <token>`.

### Parameters

- `provider` (query, string, default `aws`)
- `tag_key` (query, string, nullable): Tag key to compute allocation coverage for. Google Cloud may omit it for any-label coverage.
- `start` (query, string, nullable)
- `end` (query, string, nullable)
- `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.
- `exclude_system` (query, boolean, default `true`): Google Cloud only: ignore goog- and k8s- labels
- `include_project_labels` (query, boolean, default `true`): Google Cloud only: count labels set on the project

### Responses

#### 200: Successful Response

- `success` (boolean, default `true`)
- `timestamp` (date-time string)
- `data` (object, required)
  - `tag_key` (string, required): Tag key the allocation is computed for, empty for any-label coverage
  - `total` (number, required): Total spend in the period
  - `tagged` (number, required): Spend attributed to a non-empty value of this tag key
  - `untagged` (number, required): Spend with no value for this tag key
  - `coverage_pct` (number, required): Percentage of total spend that is tagged
  - `by_value` (array of object, required): Per-value breakdown of tagged spend
    - `value` (string, required): Tag value
    - `cost` (number, required): Cost attributed to this tag value
    - `pct` (number, required): Share of tagged spend for this value
  - `by_key` (array of object, nullable): Coverage per label key. Google Cloud only.
    - `key` (string, required): Label key
    - `cost` (number, required): Spend carrying this key
    - `coverage_pct` (number, required): Share of total spend carrying this key
    - `sources` (array of string, required): Where the key was set: user, project, kubernetes or system
  - `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)