Top topics by data volume (POST)

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.

POST/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 POST '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: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"tenant_ids\": [\n    \"string\"\n  ]\n}"
});

import requests

response = requests.post(
    "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": {}
    }
  ]
}