Top topics by data volume

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.

GET/billing/usage/top-topics

Authorization

AuthorizationBearer token · headerrequired

Query parameters

start_datestring<date>required

First day to count, inclusive (YYYY-MM-DD).

end_datestring<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.

directionUsageDirectionEnum

Which direction to rank topics by: 'in' for bytes ingested by your sources, 'out' for bytes delivered to your destinations.

Allowed:inout

limitinteger

How many topics to list individually (1-50). Everything below that is folded into others.

min 1 · max 50 · default: 10

tenant_idsstring

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

application/json

Any of:

UsageTopTopicsReqBody

tenant_idsstring[] | string | null

Sub-account tenant IDs, as an array or a comma-separated string (max 100). Takes precedence over the query parameter.

Show properties

Any of:

string[] | string

Any of:

string[]

Array of string

string

string

string

null

null

null

null

Responses

200

Successful Response

directionUsageDirectionEnumrequired

Which side of the pipeline a volume figure describes.

Allowed:inout

start_datestring<date>required

First day counted, inclusive, echoing the request.

end_datestring<date>required

Day counting stopped at, exclusive, echoing the request.

topicsUsageTopicVolume[]

The top-N topics, largest first.

Show properties

Array of UsageTopicVolume

topicstringrequired

Full Kafka topic name, e.g. source_66c1f2a9b4d3e5f7a8b9c0d1.public.orders.

topic_display_namestringrequired

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_idstring | null

Id of the source or transform that produces this topic; null when it cannot be resolved.

Show properties

Any of:

string

string

null

null

producer_typestring | null

What produces the topic: 'source' or 'transform'; null when unresolved.

Show properties

Any of:

string

string

null

null

producer_namestring | null

Display name of the producing connector, for showing alongside the topic; null when unresolved.

Show properties

Any of:

string

string

null

null

volume_bytesnumber

Bytes attributed to this topic over the window.

default: 0

volume_gbnumber

The same figure in decimal GB (bytes / 1e9), rounded to 4dp.

default: 0

percentagenumber

Share of the window's total volume, 0-100, rounded to 2dp.

default: 0

othersUsageTopTopicsOthers

Everything outside the top-N, rolled up so the parts sum to the total.

Show properties

topic_countinteger

How many topics are folded into this rollup.

default: 0

volume_bytesnumber

Their combined volume in bytes.

default: 0

volume_gbnumber

Their combined volume in decimal GB, rounded to 4dp.

default: 0

percentagenumber

Their combined share of the total, 0-100, rounded to 2dp.

default: 0

total_volume_bytesnumber

Total across all topics in the window, in bytes.

default: 0

total_volume_gbnumber

The same total in decimal GB, rounded to 4dp.

default: 0

422

Validation Error

detailValidationError[]

Show properties

Array of ValidationError

locstring | integer[]required

Show properties

Array of string | integer

Any of:

string

string

integer

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Request

curl -X GET 'https://api.streamkap.com/billing/usage/top-topics?start_date=2019-08-24&end_date=2019-08-24' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "tenant_ids": [
    "string"
  ]
}'

const response = await fetch("https://api.streamkap.com/billing/usage/top-topics?start_date=2019-08-24&end_date=2019-08-24", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"tenant_ids\": [\n    \"string\"\n  ]\n}"
});

import requests

response = requests.get(
    "https://api.streamkap.com/billing/usage/top-topics?start_date=2019-08-24&end_date=2019-08-24",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"tenant_ids\": [\n    \"string\"\n  ]\n}",
)

Response

{
  "direction": "in",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "topics": [
    {
      "topic": "string",
      "topic_display_name": "string",
      "producer_id": "string",
      "producer_type": "string",
      "producer_name": "string",
      "volume_bytes": 0,
      "volume_gb": 0,
      "percentage": 0
    }
  ],
  "others": {
    "topic_count": 0,
    "volume_bytes": 0,
    "volume_gb": 0,
    "percentage": 0
  },
  "total_volume_bytes": 0,
  "total_volume_gb": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}