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

# Top topics by data volume (POST)

`POST /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/post.ts> (a function with typed inputs; its response is checked against the schema)

Identical filters and response to GET /billing/usage/top-topics, which is the one to prefer. Use this when the query string would be too long for a URL — typically a parent account naming a hundred sub-accounts. Body values take precedence over query parameters.

## 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/post.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)