# Cost grouped by tag value

> Returns spend grouped by tag_value for a given tag_key (e.g., team, tribe, squad, cost-center). Includes a per-team category breakdown.

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


## GET /api/v1/costs/by-tag

Returns spend grouped by tag_value for a given tag_key (e.g., team, tribe, squad, cost-center). Includes a per-team category breakdown.

### Authentication

Send `Authorization: Bearer <token>`.

### Parameters

- `provider` (query, string, default `aws`)
- `tag_key` (query, string, default `team`)
- `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.

### Responses

#### 200: Successful Response

- `success` (boolean, default `true`)
- `timestamp` (date-time string)
- `data` (object, required)
  - `tag_key` (string, required)
  - `origin` (one of `provider`, `virtual`, required): virtual when tag_key names a virtual tag, whose unmapped total is exactly the spend no rule assigned
  - `teams` (array of object, required)
    - `id` (string, required)
    - `label` (string, required)
    - `total` (number, required)
    - `total_pct` (number, required)
    - `categories` (object, required)
      - `compute` (number, default `0`)
      - `storage` (number, default `0`)
      - `network` (number, default `0`)
      - `database` (number, default `0`)
      - `other` (number, default `0`)
  - `unmapped` (object, required)
    - `total` (number, required)
  - `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)