Search topics (POST)

POST alternative for GET /topics/details. Use when URL length limits are exceeded (e.g., 100+ entity IDs). Supports both query parameters and request body. Body parameters take precedence over query parameters.

POST/topics/details/search

Authorization

AuthorizationBearer token · headerrequired

Query parameters

entity_typestring

Filter by entity type(s). Single value (e.g., 'sources') or comma-separated (e.g., 'sources,transforms'). Valid types: sources, destinations, transforms, pipelines, manual, agents. Types given alongside entity_id but owning none of those IDs (e.g. 'agents', which has no picker) match on type alone rather than being AND-ed against the ID list.

topic_idstring

partial_namestring

Topic id

pageinteger

default: 1

page_sizeinteger

default: 10

entity_idstring

Filter by specific entity IDs (comma-separated list)

destination_idsstring

Narrow the result to topics DELIVERED to these destinations (comma-separated). Orthogonal to entity_type/entity_id, which select the topics' PRODUCER: combining the two expresses 'produced by these sources and delivered to these destinations'. Distinct from entity_type=destinations, which answers 'the topics this destination consumes' on its own.

include_dlqboolean

Include Dead Letter Queue (DLQ) topics in results. Set to false to exclude DLQ topics.

default: true

include_internalboolean

Include Streamkap and Kafka Connect internal topics (signal, state, and Kafka Connect offsets/configs/status) in the result; they carry connector='internal:<klass>'. Not available to regular tenant API calls: setting it returns 403.

default: false

snapshotstring

Filter topics by snapshot status. Comma-separated for multiple statuses (e.g., 'running', 'completed,failed'). Valid statuses: running, completed, failed, pending, cancelled, completed_with_warnings

etastring

Filter by snapshot ETA in milliseconds. Format: 'operator:value' (e.g., 'gt:60000', 'lte:300000'). Valid operators: gt (>), lt (<), gte (>=), lte (<=), eq (=), ne (!=). Topics without ETA (null/0) are excluded when filtering.

timestamp_fromstring

Start timestamp for filtering topics by activity period (ISO 8601 format)

timestamp_tostring

End timestamp for filtering topics by activity period (ISO 8601 format)

time_typestring

Time aggregation type for filtering active topics (only applies when timestamp_from/to are specified)

value_formatstring

Filter by serialization value format. Valid values: avro, json, json_schema, protobuf, string, bytearray. Case-insensitive. Omit or pass null to return all formats.

has_errorsboolean

Filter topics by error status. true = only topics with recordErrorTotal > 0, false = only topics with recordErrorTotal == 0, null/omit = return all topics.

orphanedboolean

Filter by orphaned status. true = only topics with 0 destinations, false = only topics with destinations.

partition_skewboolean

Filter by partition skew. true = only topics where max partition lag > 2x average.

sortstring

Sort field. Valid values: DB fields (name, connector, entity_type, entity_name), snapshot_status (sources only), or Kafka-admin fields (partition_count, replication_factor, retention_ms, lastMessageTimestamp).

sort_dirstring

default: "asc"

Allowed:ascdesc

tag_idsstring

Filter by tag IDs. Comma-separated list (e.g., 'tag1,tag2'). Use with tag_filter_operation to control AND/OR logic.

tag_filter_operationstring

Tag filter logic: 'or' (default) matches any tag, 'and' matches all tags.

default: "or"

Request body

application/json

Any of:

TopicDetailsReqBody

entity_idstring[] | string | null

List of entity IDs (as array) or comma-separated string. Body takes precedence over query params.

Show properties

Any of:

string[]

Array of string

string

string

string

null

null

destination_idsstring[] | string | null

Show properties

Any of:

string[]

Array of string

string

string

string

null

null

snapshotstring[] | string | null

List of snapshot statuses (as array) or comma-separated string. Body takes precedence over query params. Valid statuses: running, completed, failed, pending, cancelled, completed_with_warnings

Show properties

Any of:

string[]

Array of string

string

string

string

null

null

value_formatstring | null

Filter by serialization value format. Valid values: avro, json, json_schema, protobuf, string, bytearray. Case-insensitive. Body takes precedence over query params.

Show properties

Any of:

string

string

null

null

has_errorsboolean | null

Filter topics by error status. true = only topics with errors, false = only topics without errors. Body takes precedence over query params.

Show properties

Any of:

boolean

boolean

null

null

orphanedboolean | null

Filter by orphaned status. true = only topics with 0 destinations, false = only topics with destinations. Body takes precedence over query params.

Show properties

Any of:

boolean

boolean

null

null

partition_skewboolean | null

Filter by partition skew. true = only topics where max partition lag > 2x average. Body takes precedence over query params.

Show properties

Any of:

boolean

boolean

null

null

tag_idsstring[] | string | null

List of tag IDs (as array) or comma-separated string. Body takes precedence over query params.

Show properties

Any of:

string[]

Array of string

string

string

string

null

null

tag_filter_operationstring | null

Tag filter logic: 'or' (default) matches any tag, 'and' matches all tags. Body takes precedence over query params.

Show properties

Any of:

string

string

null

null

null

null

Responses

200

Successful Response

pageinteger

Current page number

default: 1

page_sizeinteger

Results per page

default: 10

totalinteger | null

Total number of results

Show properties

Any of:

integer

integer

null

null

has_nextboolean | null

Whether more pages exist

Show properties

Any of:

boolean

boolean

null

null

resultTopicDetailsRes[]required

Show properties

Array of TopicDetailsRes

idstringrequired

namestringrequired

entityTopicDetailsEntityrequired

Show properties

entity_typeTopicDetailsEntityTypeEnumrequired

Enum for topic entity types (producer types).

Allowed:sourcesdestinationstransformspipelinesmanualagents

entity_idstringrequired

namestringrequired

connectorSourceConnectorEnum | DestinationConnectorEnum | TransformsLibraryEnum | stringrequired

Show properties

Any of:

SourceConnectorEnum

string

DestinationConnectorEnum

string

TransformsLibraryEnum

string

string

string

topic_idsstring[]required

topic_db_idsstring[]required

display_namestringrequired

filtered_snapshot_languagestring | null

Show properties

Any of:

string

string

null

null

prefixstring | null

Show properties

Any of:

string

string

null

null

serializationTopicSerialization | null

Serialization format information for this topic (inherited from producer)

Show properties

Any of:

TopicSerialization

key_formatSerializationFormatEnum

Serialization format for message keys (e.g., avro, json, string)

default: "unknown"

Allowed:avrojsonjson_schemaprotobufstringbytearrayunknown

value_formatSerializationFormatEnum

Serialization format for message values (e.g., avro, json, protobuf)

default: "unknown"

Allowed:avrojsonjson_schemaprotobufstringbytearrayunknown

key_converterstring | null

Converter class for message keys

Show properties

Any of:

string

string

null

null

value_converterstring | null

Converter class for message values

Show properties

Any of:

string

string

null

null

schema_registry_enabledboolean

Whether Schema Registry is used for this topic's serialization

default: false

null

null

tagsstring[] | null

List of tag IDs assigned to this topic

Show properties

Any of:

string[]

Array of string

string

null

null

broker_onlyboolean

True when this topic exists on the Kafka broker but is not tracked by Streamkap (only possible with include_internal=true).

default: false

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/topics/details/search' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "entity_id": [
    "string"
  ],
  "destination_ids": [
    "string"
  ],
  "snapshot": [
    "string"
  ],
  "value_format": "string",
  "has_errors": true,
  "orphaned": true,
  "partition_skew": true,
  "tag_ids": [
    "string"
  ],
  "tag_filter_operation": "and"
}'

const response = await fetch("https://api.streamkap.com/topics/details/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"entity_id\": [\n    \"string\"\n  ],\n  \"destination_ids\": [\n    \"string\"\n  ],\n  \"snapshot\": [\n    \"string\"\n  ],\n  \"value_format\": \"string\",\n  \"has_errors\": true,\n  \"orphaned\": true,\n  \"partition_skew\": true,\n  \"tag_ids\": [\n    \"string\"\n  ],\n  \"tag_filter_operation\": \"and\"\n}"
});

import requests

response = requests.post(
    "https://api.streamkap.com/topics/details/search",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"entity_id\": [\n    \"string\"\n  ],\n  \"destination_ids\": [\n    \"string\"\n  ],\n  \"snapshot\": [\n    \"string\"\n  ],\n  \"value_format\": \"string\",\n  \"has_errors\": true,\n  \"orphaned\": true,\n  \"partition_skew\": true,\n  \"tag_ids\": [\n    \"string\"\n  ],\n  \"tag_filter_operation\": \"and\"\n}",
)

Response

{
  "page": 1,
  "page_size": 10,
  "total": 0,
  "has_next": true,
  "result": [
    {
      "id": "string",
      "name": "string",
      "entity": {
        "entity_type": "sources",
        "entity_id": "string",
        "name": "string",
        "connector": "alloydb",
        "topic_ids": [
          "string"
        ],
        "topic_db_ids": [
          "string"
        ],
        "display_name": "string",
        "filtered_snapshot_language": "string"
      },
      "prefix": "string",
      "serialization": {
        "key_format": "unknown",
        "value_format": "unknown",
        "key_converter": "string",
        "value_converter": "string",
        "schema_registry_enabled": false
      },
      "tags": [
        "string"
      ],
      "broker_only": false
    }
  ]
}

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