---
title: "Top topics by data volume"
method: GET
path: "/billing/usage/top-topics"
tags: ["Usage"]
---

# Top topics by data volume

`GET /billing/usage/top-topics`

## Request

- Base URL: `https://api.streamkap.com`
- URL: `https://api.streamkap.com/billing/usage/top-topics`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/streamkap/apis/streamkap-rest-api/docs/billing/usage/top-topics/get.ts> (a function with typed inputs; its response is checked against the schema)

Rank your Kafka topics by the data volume they moved over a date range, largest first, with everything past the requested limit folded into an `others` rollup so the parts add up to the total. Volumes are returned in both bytes and decimal GB.

Unlike the other usage endpoints, which report six fixed rolling windows, this one takes an explicit range — so it is the one that can answer which topics drove a given month's bill. `end_date` is exclusive.

`direction=in` ranks by what your sources ingested; `direction=out` by what your destinations delivered. Out-direction figures are per topic consumed, so a topic read by several destinations appears once with their combined volume.

## Query parameters

- `start_date` string, date, required: First day to count, inclusive (YYYY-MM-DD).
- `end_date` string, date, required: Day to stop at, EXCLUSIVE (YYYY-MM-DD) — pass the day after the last day you want counted. For all of June 2026: start_date=2026-06-01, end_date=2026-07-01.
- `direction` 'in' | 'out': Which side of the pipeline a volume figure describes.
- `limit` integer: How many topics to list individually (1-50). Everything below that is folded into `others`.
- `tenant_ids` string, nullable: Comma-separated sub-account tenant IDs to include alongside your own, for a parent account. Each is verified against your tenant tree. Omit to report only your own tenant.

## Request body

- UsageTopTopicsReqBody: Body model for POST /billing/usage/top-topics. Exists for the same reason as GetUsageMetricsReqBody: a parent account with a hundred sub-accounts exceeds the URL length limit. Body values take precedence over query params.
  - `tenant_ids` union: Sub-account tenant IDs, as an array or a comma-separated string (max 100). Takes precedence over the query parameter.
    - string[]
    - string

## Response `200`

Successful Response

- UsageTopTopicsRes: Per-topic volume breakdown for one account over an explicit date range. `topics` plus `others` account for the whole window, so the two sum to `total_volume_*`. Note for anyone comparing this against the admin app's top-topics view: for a parent account the admin view rolls up Frontegg sub-accounts automatically, whereas this reports only the tenants you asked for. Same query, deliberately different scope.
  - `direction` 'in' | 'out', required: Which side of the pipeline a volume figure describes.
  - `start_date` string, date, required: First day counted, inclusive, echoing the request.
  - `end_date` string, date, required: Day counting stopped at, exclusive, echoing the request.
  - `topics` UsageTopicVolume[]: The top-N topics, largest first.
    - `topic` string, required: Full Kafka topic name, e.g. source_66c1f2a9b4d3e5f7a8b9c0d1.public.orders.
    - `topic_display_name` string, required: The topic without its producing connector's id prefix, e.g. public.orders. Falls back to the full topic name when the prefix is not recognised.
    - `producer_id` string, nullable: Id of the source or transform that produces this topic; null when it cannot be resolved.
    - `producer_type` string, nullable: What produces the topic: 'source' or 'transform'; null when unresolved.
    - `producer_name` string, nullable: Display name of the producing connector, for showing alongside the topic; null when unresolved.
    - `volume_bytes` number: Bytes attributed to this topic over the window.
    - `volume_gb` number: The same figure in decimal GB (bytes / 1e9), rounded to 4dp.
    - `percentage` number: Share of the window's total volume, 0-100, rounded to 2dp.
  - `others` UsageTopTopicsOthers: Everything outside the top-N, rolled up so the parts sum to the total.
    - `topic_count` integer: How many topics are folded into this rollup.
    - `volume_bytes` number: Their combined volume in bytes.
    - `volume_gb` number: Their combined volume in decimal GB, rounded to 4dp.
    - `percentage` number: Their combined share of the total, 0-100, rounded to 2dp.
  - `total_volume_bytes` number: Total across all topics in the window, in bytes.
  - `total_volume_gb` number: The same total in decimal GB, rounded to 4dp.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-01** `50e54c2e65f2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/streamkap/apis/streamkap-rest-api/changes/billing/usage/top-topics/get.md)

---

[API](https://skmtc.dev/streamkap/apis/streamkap-rest-api.md) - [All operations](https://skmtc.dev/streamkap/apis/streamkap-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/streamkap/apis/streamkap-rest-api/revisions/56dda39bb53c?raw)