> For the complete documentation index, see [llms.txt](https://docs.lenses.io/latest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lenses.io/latest/api-reference/reference/consumer-groups.md).
# Consumer Groups
Kafka consumer group management
## GET /api/v1/consumer-groups
> Lists consumer-group partition rows across all environments as a flat\
> grid keyed by (environment, consumer\_group, topic, partition). Filter\
> with name\_contains, state, environment, topic and/or min\_lag. Sort any\
> rendered column via sort + order (default: lag desc). Each row carries\
> a data\_freshness envelope with last\_retrieved\_at and stale.
```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.2"},"tags":[{"name":"hq_consumer-groups","description":"Kafka consumer group management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_ConsumerGroupGrid":{"type":"object","description":"Paginated flat grid of consumer-group rows keyed by\n(environment, consumer_group, topic, partition). Sorting and filtering\noperate on individual grid cells (e.g. \"sort by partition lag desc\").\n","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/hq_ConsumerGroupRow"}},"next_cursor":{"type":"string","description":"Opaque cursor for fetching the next page. Absent if no more results."}},"required":["items"]},"hq_ConsumerGroupRow":{"type":"object","description":"One row of the cross-environment flat grid keyed by\n(environment, consumer_group, topic, partition).\n\nEach row carries per-partition offsets/lag plus per-group context\n(state, coordinator, lrn, freshness) sufficient to be rendered and\nfiltered independently.\n","properties":{"environment":{"type":"string","description":"Environment this row belongs to."},"consumer_group":{"type":"string","description":"Consumer group ID."},"lrn":{"type":"string","description":"Lenses Resource Name for client-side RBAC. Format:\nkafka:consumer-group:{environment}/kafka/{consumer_group}.\n"},"topic":{"type":"string","description":"Topic name."},"partition":{"type":"integer","minimum":0,"description":"Partition number."},"state":{"$ref":"#/components/schemas/hq_GlobalConsumerGroupState"},"coordinator":{"$ref":"#/components/schemas/hq_ConsumerGroupCoordinator"},"members_count":{"type":"integer","description":"Number of members in the consumer group."},"consumer_id":{"type":"string","description":"Consumer member assigned to this partition (if any)."},"current_offset":{"type":"integer","format":"int64","description":"Current committed offset. Absent if no committed offset."},"start_offset":{"type":"integer","format":"int64","description":"Earliest available offset for the partition."},"log_end_offset":{"type":"integer","format":"int64","description":"Log-end offset for the partition."},"lag":{"type":"integer","format":"int64","description":"Offset lag (log_end_offset - current_offset)."},"lag_ms":{"type":"integer","format":"int64","nullable":true,"description":"Estimated time-based lag in milliseconds (offset lag divided by\nthe producer rate over a sliding window). Approximates how far\nbehind in time the consumer is. Matches the agent's lag_ms. Null\nwhen the producer rate is unavailable (idle topic or insufficient\nsamples); 0 means caught up.\n"},"lag_catch_up_ms":{"type":"integer","format":"int64","nullable":true,"description":"Estimated milliseconds for the lag to reach zero at the current\nnet consumption rate. Null when the consumer is not gaining (lag\nflat or growing) or history is insufficient.\n"},"lag_trend":{"$ref":"#/components/schemas/hq_ConsumerGroupLagTrend"},"leader_epoch":{"type":"integer","format":"int32","description":"Leader epoch of the committed offset (optional)."},"metadata":{"type":"string","description":"Committed-offset metadata string (may be empty)."},"data_freshness":{"$ref":"#/components/schemas/hq_ConsumerGroupDataFreshness"}},"required":["environment","consumer_group","lrn","topic","partition","state","members_count","lag_ms","lag_catch_up_ms","data_freshness"]},"hq_GlobalConsumerGroupState":{"type":"string","description":"Consumer group state. Kafka's consumer group states are collapsed into five values: stable (STABLE); rebalancing (PREPARING_REBALANCE, COMPLETING_REBALANCE, and the consumer-protocol rebalance phases ASSIGNING and RECONCILING); empty (EMPTY); dead (DEAD); and unknown (when the broker reports no state, or the value is not recognised).","enum":["stable","rebalancing","empty","dead","unknown"]},"hq_ConsumerGroupCoordinator":{"type":"object","properties":{"id":{"type":"integer","description":"Broker ID of the coordinator."},"host":{"type":"string","description":"Hostname of the coordinator."},"port":{"type":"integer","description":"Port of the coordinator."},"rack":{"type":"string","description":"Rack of the coordinator."}},"required":["id","host","port"]},"hq_ConsumerGroupLagTrend":{"type":"string","description":"Direction of a consumer group partition's lag over the recent window. The value is \"unknown\" until enough samples exist.","enum":["increasing","decreasing","stable","unknown"]},"hq_ConsumerGroupDataFreshness":{"type":"object","description":"Freshness metadata for this consumer group entry, indicating when the\ndata was last successfully retrieved and whether a retrieval error was\nencountered.\n","properties":{"last_retrieved_at":{"type":"string","format":"date-time","description":"Timestamp of the last successful data retrieval for this row.\nNot advanced on failed attempts.\n"},"stale":{"type":"boolean","description":"True if the most recent refresh attempt for this row failed\n(agent unreachable, gRPC timeout, RBAC error). The row's other\nfields still reflect the last successful retrieval at\nlast_retrieved_at, but the UI should surface a \"data may be\noutdated\" indicator. False on success.\n"},"refresh_interval_seconds":{"type":"integer","description":"Configured background-refresh interval in seconds. UI hint for\nrendering staleness indicators.\n"}},"required":["last_retrieved_at","stale"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/consumer-groups":{"get":{"description":"Lists consumer-group partition rows across all environments as a flat\ngrid keyed by (environment, consumer_group, topic, partition). Filter\nwith name_contains, state, environment, topic and/or min_lag. Sort any\nrendered column via sort + order (default: lag desc). Each row carries\na data_freshness envelope with last_retrieved_at and stale.\n","operationId":"listConsumerGroupRows","parameters":[{"name":"pagination_cursor","in":"query","description":"Cursor for pagination. Pass next_cursor from previous response. Cursors reflect the dataset at the time of the first page request; groups added or removed between pages may appear duplicated or be skipped. Fetch from page 1 again to get a fully consistent view.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of items to return. Greater than 0, less than 1000.","schema":{"type":"integer","default":25,"minimum":1,"maximum":999}},{"name":"name_contains","in":"query","description":"Filter rows by consumer-group name substring.","schema":{"type":"string"}},{"name":"state","in":"query","description":"Filter rows by consumer-group state.","schema":{"type":"string","enum":["stable","rebalancing","empty","dead","unknown"]}},{"name":"environment","in":"query","description":"Filter rows to these environments (comma-separated). All environments are included when no value is supplied.","schema":{"type":"string"}},{"name":"topic","in":"query","description":"Filter rows by topic name (case-insensitive substring match).","schema":{"type":"string"}},{"name":"min_lag","in":"query","description":"Filter to partitions whose lag is greater than or equal to this value. Partitions with no known lag (null lag) are excluded by this filter.","schema":{"type":"integer","minimum":0}},{"name":"sort","in":"query","description":"Column to sort the grid by. Defaults to lag.","schema":{"type":"string","default":"lag","enum":["lag","lag_ms","lag_catch_up_ms","current_offset","start_offset","log_end_offset","leader_epoch","partition","last_retrieved_at","environment","consumer_group","topic","consumer_id","metadata","lag_trend","state","members_count","stale"]}},{"name":"order","in":"query","description":"Sort direction. Defaults to desc.","schema":{"type":"string","default":"desc","enum":["asc","desc"]}}],"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_ConsumerGroupGrid"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_consumer-groups"]}}}}
```
## GET /api/v1/consumer-groups/{env\_name}
> Lists consumer groups for a specific environment at (env, group)\
> granularity. Active API for the environment-scoped UI sidebar.\
> Use GET /v1/consumer-groups for the cross-environment flat grid.
```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.2"},"tags":[{"name":"hq_consumer-groups","description":"Kafka consumer group management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_ConsumerGroupList":{"type":"object","description":"Paginated list of consumer groups at (env, group) granularity, using\ncursor-based pagination. Complements ConsumerGroupGrid for\nenvironment-scoped sidebar views where per-partition rows are not needed.\n","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/hq_ConsumerGroup"}},"next_cursor":{"type":"string","description":"Opaque cursor for fetching the next page. Absent if no more results."}},"required":["items"]},"hq_ConsumerGroup":{"type":"object","description":"Consumer-group summary at (environment, name) granularity. Used for\nthe environment-scoped list and as the base of ConsumerGroupDetail.\nFor the cross-environment flat grid use ConsumerGroupRow instead.\n","properties":{"environment":{"type":"string","description":"Environment this consumer group belongs to."},"name":{"type":"string","description":"Consumer group ID."},"lrn":{"type":"string","description":"Lenses Resource Name for client-side RBAC. Format:\nkafka:consumer-group:{environment}/kafka/{name}.\n"},"state":{"$ref":"#/components/schemas/hq_GlobalConsumerGroupState"},"coordinator":{"$ref":"#/components/schemas/hq_ConsumerGroupCoordinator"},"members_count":{"type":"integer","description":"Number of members in the consumer group."},"topics":{"type":"array","items":{"type":"string"},"description":"Topics subscribed by this consumer group."},"lag":{"$ref":"#/components/schemas/hq_ConsumerGroupLagSummary"},"data_freshness":{"$ref":"#/components/schemas/hq_ConsumerGroupDataFreshness"}},"required":["environment","name","lrn","state","members_count","topics","lag","data_freshness"]},"hq_GlobalConsumerGroupState":{"type":"string","description":"Consumer group state. Kafka's consumer group states are collapsed into five values: stable (STABLE); rebalancing (PREPARING_REBALANCE, COMPLETING_REBALANCE, and the consumer-protocol rebalance phases ASSIGNING and RECONCILING); empty (EMPTY); dead (DEAD); and unknown (when the broker reports no state, or the value is not recognised).","enum":["stable","rebalancing","empty","dead","unknown"]},"hq_ConsumerGroupCoordinator":{"type":"object","properties":{"id":{"type":"integer","description":"Broker ID of the coordinator."},"host":{"type":"string","description":"Hostname of the coordinator."},"port":{"type":"integer","description":"Port of the coordinator."},"rack":{"type":"string","description":"Rack of the coordinator."}},"required":["id","host","port"]},"hq_ConsumerGroupLagSummary":{"type":"object","properties":{"total":{"type":"integer","format":"int64","description":"Total offset lag across all partitions. Null when no partition has a computable offset lag (distinct from a genuine zero lag)."},"min":{"type":"integer","format":"int64","description":"Minimum offset lag across partitions. Null when no partition has a computable offset lag."},"min_partition":{"$ref":"#/components/schemas/hq_ConsumerGroupPartitionRef","description":"The partition with the minimum offset lag. Null exactly when min is\nnull (no partition has a computable offset lag). On a tie, the\n(topic, partition) that sorts first.\n"},"max":{"type":"integer","format":"int64","description":"Maximum offset lag across partitions. Null when no partition has a computable offset lag."},"max_partition":{"$ref":"#/components/schemas/hq_ConsumerGroupPartitionRef","description":"The partition with the maximum offset lag. Same nullability and\ntie-breaking rules as min_partition.\n"},"total_ms":{"type":"integer","format":"int64","description":"Total time-based lag in milliseconds. Null when not computable."},"min_ms":{"type":"integer","format":"int64","description":"Minimum time-based lag in milliseconds. Null when not computable."},"max_ms":{"type":"integer","format":"int64","description":"Maximum time-based lag in milliseconds. Null when not computable."}}},"hq_ConsumerGroupPartitionRef":{"type":"object","description":"Identifies a single topic-partition.","properties":{"topic":{"type":"string","description":"Topic name."},"partition":{"type":"integer","minimum":0,"description":"Partition number."}},"required":["topic","partition"]},"hq_ConsumerGroupDataFreshness":{"type":"object","description":"Freshness metadata for this consumer group entry, indicating when the\ndata was last successfully retrieved and whether a retrieval error was\nencountered.\n","properties":{"last_retrieved_at":{"type":"string","format":"date-time","description":"Timestamp of the last successful data retrieval for this row.\nNot advanced on failed attempts.\n"},"stale":{"type":"boolean","description":"True if the most recent refresh attempt for this row failed\n(agent unreachable, gRPC timeout, RBAC error). The row's other\nfields still reflect the last successful retrieval at\nlast_retrieved_at, but the UI should surface a \"data may be\noutdated\" indicator. False on success.\n"},"refresh_interval_seconds":{"type":"integer","description":"Configured background-refresh interval in seconds. UI hint for\nrendering staleness indicators.\n"}},"required":["last_retrieved_at","stale"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/consumer-groups/{env_name}":{"get":{"description":"Lists consumer groups for a specific environment at (env, group)\ngranularity. Active API for the environment-scoped UI sidebar.\nUse GET /v1/consumer-groups for the cross-environment flat grid.\n","operationId":"listConsumerGroupsByEnvironment","parameters":[{"in":"path","name":"env_name","required":true,"schema":{"type":"string"}},{"name":"pagination_cursor","in":"query","description":"Cursor for pagination. Pass next_cursor from previous response.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of items to return. Greater than 0, less than 1000.","schema":{"type":"integer","default":25,"minimum":1,"maximum":999}},{"name":"name_contains","in":"query","description":"Filter consumer groups by name substring.","schema":{"type":"string"}},{"name":"state","in":"query","description":"Filter consumer groups by state.","schema":{"type":"string","enum":["stable","rebalancing","empty","dead","unknown"]}},{"name":"topic","in":"query","description":"Filter to consumer groups consuming a topic whose name contains this substring (case-insensitive).","schema":{"type":"string"}},{"name":"min_lag","in":"query","description":"Filter to consumer groups whose total lag is greater than or equal to this value. Groups with no known total lag (null lag) are excluded by this filter.","schema":{"type":"integer","minimum":0}},{"name":"sort","in":"query","description":"Column to sort the list by. Defaults to consumer_group.","schema":{"type":"string","default":"consumer_group","enum":["consumer_group","state","members_count","lag_total","lag_min","lag_max","lag_total_ms","lag_min_ms","lag_max_ms","last_retrieved_at","stale"]}},{"name":"order","in":"query","description":"Sort direction. Defaults to asc.","schema":{"type":"string","default":"asc","enum":["asc","desc"]}}],"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_ConsumerGroupList"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_consumer-groups"]}}}}
```
## GET /api/v1/consumer-groups/{env\_name}/{consumer\_group\_name}
> Retrieves details for a single consumer group.
```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.2"},"tags":[{"name":"hq_consumer-groups","description":"Kafka consumer group management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_ConsumerGroupDetail":{"description":"Full per-group detail including member-level information and\nper-partition offset data (nested as topic_partitions).\n","allOf":[{"$ref":"#/components/schemas/hq_ConsumerGroup"},{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/hq_ConsumerGroupMember"},"description":"Members of the consumer group."},"topic_partitions":{"type":"array","items":{"$ref":"#/components/schemas/hq_ConsumerGroupTopicPartition"},"description":"Topic-partition details with offsets and lag."}},"required":["members","topic_partitions"]}]},"hq_ConsumerGroup":{"type":"object","description":"Consumer-group summary at (environment, name) granularity. Used for\nthe environment-scoped list and as the base of ConsumerGroupDetail.\nFor the cross-environment flat grid use ConsumerGroupRow instead.\n","properties":{"environment":{"type":"string","description":"Environment this consumer group belongs to."},"name":{"type":"string","description":"Consumer group ID."},"lrn":{"type":"string","description":"Lenses Resource Name for client-side RBAC. Format:\nkafka:consumer-group:{environment}/kafka/{name}.\n"},"state":{"$ref":"#/components/schemas/hq_GlobalConsumerGroupState"},"coordinator":{"$ref":"#/components/schemas/hq_ConsumerGroupCoordinator"},"members_count":{"type":"integer","description":"Number of members in the consumer group."},"topics":{"type":"array","items":{"type":"string"},"description":"Topics subscribed by this consumer group."},"lag":{"$ref":"#/components/schemas/hq_ConsumerGroupLagSummary"},"data_freshness":{"$ref":"#/components/schemas/hq_ConsumerGroupDataFreshness"}},"required":["environment","name","lrn","state","members_count","topics","lag","data_freshness"]},"hq_GlobalConsumerGroupState":{"type":"string","description":"Consumer group state. Kafka's consumer group states are collapsed into five values: stable (STABLE); rebalancing (PREPARING_REBALANCE, COMPLETING_REBALANCE, and the consumer-protocol rebalance phases ASSIGNING and RECONCILING); empty (EMPTY); dead (DEAD); and unknown (when the broker reports no state, or the value is not recognised).","enum":["stable","rebalancing","empty","dead","unknown"]},"hq_ConsumerGroupCoordinator":{"type":"object","properties":{"id":{"type":"integer","description":"Broker ID of the coordinator."},"host":{"type":"string","description":"Hostname of the coordinator."},"port":{"type":"integer","description":"Port of the coordinator."},"rack":{"type":"string","description":"Rack of the coordinator."}},"required":["id","host","port"]},"hq_ConsumerGroupLagSummary":{"type":"object","properties":{"total":{"type":"integer","format":"int64","description":"Total offset lag across all partitions. Null when no partition has a computable offset lag (distinct from a genuine zero lag)."},"min":{"type":"integer","format":"int64","description":"Minimum offset lag across partitions. Null when no partition has a computable offset lag."},"min_partition":{"$ref":"#/components/schemas/hq_ConsumerGroupPartitionRef","description":"The partition with the minimum offset lag. Null exactly when min is\nnull (no partition has a computable offset lag). On a tie, the\n(topic, partition) that sorts first.\n"},"max":{"type":"integer","format":"int64","description":"Maximum offset lag across partitions. Null when no partition has a computable offset lag."},"max_partition":{"$ref":"#/components/schemas/hq_ConsumerGroupPartitionRef","description":"The partition with the maximum offset lag. Same nullability and\ntie-breaking rules as min_partition.\n"},"total_ms":{"type":"integer","format":"int64","description":"Total time-based lag in milliseconds. Null when not computable."},"min_ms":{"type":"integer","format":"int64","description":"Minimum time-based lag in milliseconds. Null when not computable."},"max_ms":{"type":"integer","format":"int64","description":"Maximum time-based lag in milliseconds. Null when not computable."}}},"hq_ConsumerGroupPartitionRef":{"type":"object","description":"Identifies a single topic-partition.","properties":{"topic":{"type":"string","description":"Topic name."},"partition":{"type":"integer","minimum":0,"description":"Partition number."}},"required":["topic","partition"]},"hq_ConsumerGroupDataFreshness":{"type":"object","description":"Freshness metadata for this consumer group entry, indicating when the\ndata was last successfully retrieved and whether a retrieval error was\nencountered.\n","properties":{"last_retrieved_at":{"type":"string","format":"date-time","description":"Timestamp of the last successful data retrieval for this row.\nNot advanced on failed attempts.\n"},"stale":{"type":"boolean","description":"True if the most recent refresh attempt for this row failed\n(agent unreachable, gRPC timeout, RBAC error). The row's other\nfields still reflect the last successful retrieval at\nlast_retrieved_at, but the UI should surface a \"data may be\noutdated\" indicator. False on success.\n"},"refresh_interval_seconds":{"type":"integer","description":"Configured background-refresh interval in seconds. UI hint for\nrendering staleness indicators.\n"}},"required":["last_retrieved_at","stale"]},"hq_ConsumerGroupMember":{"type":"object","description":"Per-member view of a consumer group. Each member is a single consumer\nprocess currently joined to the group, with the membership details the\nbroker reports.\n","properties":{"consumer_id":{"type":"string","description":"Unique consumer member ID within the group."},"client_id":{"type":"string","description":"Client ID of the consumer."},"host":{"type":"string","description":"Host of the consumer."},"group_instance_id":{"type":"string","description":"Static membership instance id assigned to the consumer. Absent for\ndynamic members that do not use static membership.\n"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/hq_ConsumerGroupMemberAssignment"},"description":"Topic-partition assignments for this member."}},"required":["consumer_id","client_id","host","assignments"]},"hq_ConsumerGroupMemberAssignment":{"type":"object","properties":{"topic":{"type":"string","description":"Topic name."},"partition":{"type":"integer","minimum":0,"description":"Partition number."}},"required":["topic","partition"]},"hq_ConsumerGroupTopicPartition":{"type":"object","description":"Per-(group, topic, partition) row combining committed offset and\npartition log position data. Used both as the building block of the\nflat grid (see ConsumerGroupRow) and as the partition-level detail\nnested under ConsumerGroupDetail.\n","properties":{"topic":{"type":"string","description":"Topic name."},"partition":{"type":"integer","minimum":0,"description":"Partition number."},"current_offset":{"type":"integer","format":"int64","description":"Current committed offset for this group, topic and partition.\nAbsent if no offset has been committed.\n"},"start_offset":{"type":"integer","format":"int64","description":"Earliest available offset for the partition (log start)."},"log_end_offset":{"type":"integer","format":"int64","description":"Log-end offset for the partition (latest)."},"lag":{"type":"integer","format":"int64","description":"Offset lag (log_end_offset - current_offset)."},"lag_ms":{"type":"integer","format":"int64","description":"Estimated time-based lag in milliseconds (offset lag divided by\nthe producer rate over a sliding window). Approximates how far\nbehind in time the consumer is. Matches the agent's lag_ms.\nAbsent when the producer rate is unavailable (idle topic or\ninsufficient samples).\n"},"lag_catch_up_ms":{"type":"integer","format":"int64","description":"Estimated milliseconds for the lag to reach zero at the current\nnet consumption rate. Absent when the consumer is not gaining\n(lag flat or growing) or history is insufficient.\n"},"lag_trend":{"$ref":"#/components/schemas/hq_ConsumerGroupLagTrend"},"leader_epoch":{"type":"integer","format":"int32","description":"Leader epoch of the committed offset. Absent when not recorded.\n"},"metadata":{"type":"string","description":"Committed-offset metadata string. May be empty.\n"},"consumer_id":{"type":"string","description":"Consumer member assigned to this partition (if any). Sourced from\nConsumerGroupMember.assignments by HQ during grid assembly.\n"}},"required":["topic","partition"]},"hq_ConsumerGroupLagTrend":{"type":"string","description":"Direction of a consumer group partition's lag over the recent window. The value is \"unknown\" until enough samples exist.","enum":["increasing","decreasing","stable","unknown"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/consumer-groups/{env_name}/{consumer_group_name}":{"get":{"description":"Retrieves details for a single consumer group.","operationId":"getConsumerGroup","parameters":[{"in":"path","name":"env_name","required":true,"schema":{"type":"string"}},{"in":"path","name":"consumer_group_name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_ConsumerGroupDetail"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_consumer-groups"]}}}}
```
## DELETE /api/v1/consumer-groups/{env\_name}/{consumer\_group\_name}
> Deletes a consumer group.
```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.2"},"tags":[{"name":"hq_consumer-groups","description":"Kafka consumer group management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/consumer-groups/{env_name}/{consumer_group_name}":{"delete":{"description":"Deletes a consumer group.","operationId":"deleteConsumerGroup","parameters":[{"in":"path","name":"env_name","required":true,"schema":{"type":"string"}},{"in":"path","name":"consumer_group_name","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Consumer group deleted successfully."},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_consumer-groups"]}}}}
```
## PUT /api/v1/consumer-groups/{env\_name}/{consumer\_group\_name}/offsets
> Sets offsets for a consumer group.
```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.2"},"tags":[{"name":"hq_consumer-groups","description":"Kafka consumer group management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_SetConsumerGroupOffsetsRequest":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/hq_OffsetResetType"},"timestamp":{"type":"string","format":"date-time","description":"Target timestamp. Required when type is timestamp."},"topics":{"type":"array","items":{"$ref":"#/components/schemas/hq_TopicPartitionOffset"},"minItems":1,"description":"Topics and partitions to set offsets for."}},"required":["type","topics"]},"hq_OffsetResetType":{"type":"string","description":"Reset strategy for the offsets.","enum":["earliest","latest","timestamp","absolute"]},"hq_TopicPartitionOffset":{"type":"object","properties":{"topic":{"type":"string","description":"Topic name."},"partitions":{"type":"array","items":{"$ref":"#/components/schemas/hq_PartitionOffset"},"minItems":1,"description":"Partitions to set offsets for. At least one partition must be listed per topic; partition discovery (\"apply to all partitions\") is not yet supported on the set-offsets path."}},"required":["topic","partitions"]},"hq_PartitionOffset":{"type":"object","properties":{"partition":{"type":"integer","minimum":0,"description":"Partition number."},"offset":{"type":"integer","format":"int64","minimum":0,"description":"Target offset. Required when type is absolute."}},"required":["partition"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/consumer-groups/{env_name}/{consumer_group_name}/offsets":{"put":{"description":"Sets offsets for a consumer group.","operationId":"setConsumerGroupOffsets","parameters":[{"in":"path","name":"env_name","required":true,"schema":{"type":"string"}},{"in":"path","name":"consumer_group_name","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_SetConsumerGroupOffsetsRequest"}}}},"responses":{"204":{"description":"Offsets set successfully."},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_consumer-groups"]}}}}
```
## DELETE /api/v1/consumer-groups/{env\_name}/{consumer\_group\_name}/offsets
> Deletes committed offsets for a consumer group at group, topic, or\
> topic-partition granularity. Omit topics (or pass an empty array) to\
> delete all committed offsets. The group must be inactive.\
> Irreversible.
```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.2"},"tags":[{"name":"hq_consumer-groups","description":"Kafka consumer group management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_DeleteConsumerGroupOffsetsRequest":{"type":"object","description":"Selects which committed offsets to delete. Omit topics or pass an\nempty array to delete all committed offsets for the group. Each entry\nmay omit partitions to delete every partition the group consumes on\nthat topic, or list partitions for topic-partition scope. The group\nmust be inactive. Irreversible.\n","properties":{"topics":{"type":"array","items":{"$ref":"#/components/schemas/hq_TopicPartitions"},"description":"Topics and partitions to delete offsets for."}}},"hq_TopicPartitions":{"type":"object","properties":{"topic":{"type":"string","description":"Topic name."},"partitions":{"type":"array","items":{"type":"integer","minimum":0},"description":"Partition numbers. If omitted, applies to all partitions of the topic."}},"required":["topic"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/consumer-groups/{env_name}/{consumer_group_name}/offsets":{"delete":{"description":"Deletes committed offsets for a consumer group at group, topic, or\ntopic-partition granularity. Omit topics (or pass an empty array) to\ndelete all committed offsets. The group must be inactive.\nIrreversible.\n","operationId":"deleteConsumerGroupOffsets","parameters":[{"in":"path","name":"env_name","required":true,"schema":{"type":"string"}},{"in":"path","name":"consumer_group_name","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_DeleteConsumerGroupOffsetsRequest"}}}},"responses":{"204":{"description":"Offsets deleted successfully."},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_consumer-groups"]}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.lenses.io/latest/api-reference/reference/consumer-groups.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.