---
title: "Get Costs By Tag"
method: GET
path: "/costs/by-tag"
---

# Get Costs By Tag

`GET /costs/by-tag`

Aggregate cost data grouped by allocation tag *or* by adapter.

The endpoint serves three callers:

* Web GUI (``Costs.tsx`` adapter table) - calls ``GET /costs/by-tag``
  and expects an array of ``{adapter, calls, tokens, cost_usd,
  share_pct, delta_7d_pct}`` rows. With ``shape=auto`` (default) and
  no ``tag_key``, this is what we return.
* Legacy callers passing ``tag_key=…`` - receive the existing
  ``{by_tag: {key: {value: cost}}}`` envelope.
* Legacy callers wanting the envelope explicitly - pass
  ``shape=tags`` and get the envelope without supplying a key.

The ``hours`` parameter controls the GUI window (default 24h).

## Query parameters

- `tag_key` string, nullable
- `hours` integer
- `shape` string

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

## Changes

- **2026-07-26** `2a1299ef19fa` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/sipyourdrink-ltd/apis/bernstein-task-server/changes/costs/by-tag/get.md)

---

[API](https://skmtc.dev/sipyourdrink-ltd/apis/bernstein-task-server.md) · [All operations](https://skmtc.dev/sipyourdrink-ltd/apis/bernstein-task-server/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sipyourdrink-ltd/bernstein-task-server/revisions/1f35e916d7e4/schema)