Updated on 2026-11-03 GMT+08:00

Resetting Consumer Group Offset to the Specified Position

Function

Kafka instances do not support resetting the consumer offset online. Before resetting, stop the client for which the offset is to be reset. After a client is stopped, the server considers the client offline only after the time period specified in ConsumerConfig.SESSION_TIMEOUT_MS_CONFIG (1000 ms by default).

Calling Method

For details, see Calling APIs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, no identity policy-based permission required for calling this API.

URI

PUT /v2/kafka/{project_id}/instances/{instance_id}/groups/{group}/reset-message-offset

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID. For details, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

instance_id

Yes

String

Definition

Instance ID. To obtain it, call the API for querying all instances.

Constraints

N/A

Range

N/A

Default Value

N/A

group

Yes

String

Definition

Consumer group name.

Constraints

N/A

Range

N/A

Default Value

N/A

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

topic

Yes

String

Definition

Topic name.

Constraints

If the input name is empty, the consumption progress of all topics will be reset.

Range

N/A

Default Value

N/A

partition

Yes

Integer

Definition

Partition ID. If the value is set to -1, all partitions are reset.

Constraints

N/A

Range

N/A

Default Value

-1.

message_offset

No

Long

Definition

Position to which the consumer group offset is reset.

Constraints

  • If the transferred offset is earlier than the current earliest offset, the current earliest offset will apply.

  • If the transferred offset is later than the current latest offset, the current latest offset will apply.

  • Either message_offset or timestamp must be specified.

Range

N/A

Default Value

N/A

timestamp

No

Long

Definition

Time to which the consumer group offset is reset. It is a UNIX timestamp, in millisecond.

Constraints

  • If the transferred timestamp is earlier than the current earliest timestamp, the current earliest timestamp will apply.

  • If the transferred timestamp is later than the current latest timestamp, the current latest timestamp will apply.

  • Either message_offset or timestamp must be specified.

Range

N/A

Default Value

N/A

Response Parameters

Status code: 204

None

Example Requests

  • Reset the consumer offset to the specified position.

    PUT https://{endpoint}/v2/kafka/{project_id}/instances/{instance_id}/groups/{group}/reset-message-offset
    
    {
      "topic" : "test",
      "partition" : 0,
      "message_offset" : 10
    }
  • Reset the consumer offset to the specified time.

    PUT https://{endpoint}/v2/kafka/{project_id}/instances/{instance_id}/groups/{group}/reset-message-offset
    
    {
      "topic" : "test",
      "partition" : 0,
      "timestamp" : 1571812144000
    }

Example Responses

None

SDK Sample Code

The SDK sample code is as follows.

  • Reset the consumer offset to the specified position.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    package com.huaweicloud.sdk.test;
    
    import com.huaweicloud.sdk.core.auth.ICredential;
    import com.huaweicloud.sdk.core.auth.BasicCredentials;
    import com.huaweicloud.sdk.core.exception.ConnectionException;
    import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
    import com.huaweicloud.sdk.core.exception.ServiceResponseException;
    import com.huaweicloud.sdk.kafka.v2.region.KafkaRegion;
    import com.huaweicloud.sdk.kafka.v2.*;
    import com.huaweicloud.sdk.kafka.v2.model.*;
    
    
    public class ResetMessageOffsetWithEngineSolution {
    
        public static void main(String[] args) {
            // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
            // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
            String ak = System.getenv("CLOUD_SDK_AK");
            String sk = System.getenv("CLOUD_SDK_SK");
            String projectId = "{project_id}";
    
            ICredential auth = new BasicCredentials()
                    .withProjectId(projectId)
                    .withAk(ak)
                    .withSk(sk);
    
            KafkaClient client = KafkaClient.newBuilder()
                    .withCredential(auth)
                    .withRegion(KafkaRegion.valueOf("<YOUR REGION>"))
                    .build();
            ResetMessageOffsetWithEngineRequest request = new ResetMessageOffsetWithEngineRequest();
            request.withInstanceId("{instance_id}");
            request.withGroup("{group}");
            ResetMessageOffsetReq body = new ResetMessageOffsetReq();
            body.withMessageOffset(10L);
            body.withPartition(0);
            body.withTopic("test");
            request.withBody(body);
            try {
                ResetMessageOffsetWithEngineResponse response = client.resetMessageOffsetWithEngine(request);
                System.out.println(response.toString());
            } catch (ConnectionException e) {
                e.printStackTrace();
            } catch (RequestTimeoutException e) {
                e.printStackTrace();
            } catch (ServiceResponseException e) {
                e.printStackTrace();
                System.out.println(e.getHttpStatusCode());
                System.out.println(e.getRequestId());
                System.out.println(e.getErrorCode());
                System.out.println(e.getErrorMsg());
            }
        }
    }
    
  • Reset the consumer offset to the specified time.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    package com.huaweicloud.sdk.test;
    
    import com.huaweicloud.sdk.core.auth.ICredential;
    import com.huaweicloud.sdk.core.auth.BasicCredentials;
    import com.huaweicloud.sdk.core.exception.ConnectionException;
    import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
    import com.huaweicloud.sdk.core.exception.ServiceResponseException;
    import com.huaweicloud.sdk.kafka.v2.region.KafkaRegion;
    import com.huaweicloud.sdk.kafka.v2.*;
    import com.huaweicloud.sdk.kafka.v2.model.*;
    
    
    public class ResetMessageOffsetWithEngineSolution {
    
        public static void main(String[] args) {
            // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
            // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
            String ak = System.getenv("CLOUD_SDK_AK");
            String sk = System.getenv("CLOUD_SDK_SK");
            String projectId = "{project_id}";
    
            ICredential auth = new BasicCredentials()
                    .withProjectId(projectId)
                    .withAk(ak)
                    .withSk(sk);
    
            KafkaClient client = KafkaClient.newBuilder()
                    .withCredential(auth)
                    .withRegion(KafkaRegion.valueOf("<YOUR REGION>"))
                    .build();
            ResetMessageOffsetWithEngineRequest request = new ResetMessageOffsetWithEngineRequest();
            request.withInstanceId("{instance_id}");
            request.withGroup("{group}");
            ResetMessageOffsetReq body = new ResetMessageOffsetReq();
            body.withTimestamp(1571812144000L);
            body.withPartition(0);
            body.withTopic("test");
            request.withBody(body);
            try {
                ResetMessageOffsetWithEngineResponse response = client.resetMessageOffsetWithEngine(request);
                System.out.println(response.toString());
            } catch (ConnectionException e) {
                e.printStackTrace();
            } catch (RequestTimeoutException e) {
                e.printStackTrace();
            } catch (ServiceResponseException e) {
                e.printStackTrace();
                System.out.println(e.getHttpStatusCode());
                System.out.println(e.getRequestId());
                System.out.println(e.getErrorCode());
                System.out.println(e.getErrorMsg());
            }
        }
    }
    
  • Reset the consumer offset to the specified position.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    # coding: utf-8
    
    import os
    from huaweicloudsdkcore.auth.credentials import BasicCredentials
    from huaweicloudsdkkafka.v2.region.kafka_region import KafkaRegion
    from huaweicloudsdkcore.exceptions import exceptions
    from huaweicloudsdkkafka.v2 import *
    
    if __name__ == "__main__":
        # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak = os.environ["CLOUD_SDK_AK"]
        sk = os.environ["CLOUD_SDK_SK"]
        projectId = "{project_id}"
    
        credentials = BasicCredentials(ak, sk, projectId)
    
        client = KafkaClient.new_builder() \
            .with_credentials(credentials) \
            .with_region(KafkaRegion.value_of("<YOUR REGION>")) \
            .build()
    
        try:
            request = ResetMessageOffsetWithEngineRequest()
            request.instance_id = "{instance_id}"
            request.group = "{group}"
            request.body = ResetMessageOffsetReq(
                message_offset=10,
                partition=0,
                topic="test"
            )
            response = client.reset_message_offset_with_engine(request)
            print(response)
        except exceptions.ClientRequestException as e:
            print(e.status_code)
            print(e.request_id)
            print(e.error_code)
            print(e.error_msg)
    
  • Reset the consumer offset to the specified time.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    # coding: utf-8
    
    import os
    from huaweicloudsdkcore.auth.credentials import BasicCredentials
    from huaweicloudsdkkafka.v2.region.kafka_region import KafkaRegion
    from huaweicloudsdkcore.exceptions import exceptions
    from huaweicloudsdkkafka.v2 import *
    
    if __name__ == "__main__":
        # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak = os.environ["CLOUD_SDK_AK"]
        sk = os.environ["CLOUD_SDK_SK"]
        projectId = "{project_id}"
    
        credentials = BasicCredentials(ak, sk, projectId)
    
        client = KafkaClient.new_builder() \
            .with_credentials(credentials) \
            .with_region(KafkaRegion.value_of("<YOUR REGION>")) \
            .build()
    
        try:
            request = ResetMessageOffsetWithEngineRequest()
            request.instance_id = "{instance_id}"
            request.group = "{group}"
            request.body = ResetMessageOffsetReq(
                timestamp=1571812144000,
                partition=0,
                topic="test"
            )
            response = client.reset_message_offset_with_engine(request)
            print(response)
        except exceptions.ClientRequestException as e:
            print(e.status_code)
            print(e.request_id)
            print(e.error_code)
            print(e.error_msg)
    
  • Reset the consumer offset to the specified position.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    package main
    
    import (
    	"fmt"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
        kafka "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/kafka/v2"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/kafka/v2/model"
        region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/kafka/v2/region"
    )
    
    func main() {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak := os.Getenv("CLOUD_SDK_AK")
        sk := os.Getenv("CLOUD_SDK_SK")
        projectId := "{project_id}"
    
        auth, err := basic.NewCredentialsBuilder().
            WithAk(ak).
            WithSk(sk).
            WithProjectId(projectId).
            SafeBuild()
    
        if err != nil {
            fmt.Println(err)
            return
        }
    
        hcClient, err := kafka.KafkaClientBuilder().
             WithRegion(region.ValueOf("<YOUR REGION>")).
             WithCredential(auth).
             SafeBuild()
    
    
        if err != nil {
            fmt.Println(err)
            return
        }
    
        client := kafka.NewKafkaClient(hcClient)
    
        request := &model.ResetMessageOffsetWithEngineRequest{}
    	request.InstanceId = "{instance_id}"
    	request.Group = "{group}"
    	messageOffsetResetMessageOffsetReq:= int64(10)
    	request.Body = &model.ResetMessageOffsetReq{
    		MessageOffset: &messageOffsetResetMessageOffsetReq,
    		Partition: int32(0),
    		Topic: "test",
    	}
    	response, err := client.ResetMessageOffsetWithEngine(request)
    	if err == nil {
            fmt.Printf("%+v\n", response)
        } else {
            fmt.Println(err)
        }
    }
    
  • Reset the consumer offset to the specified time.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    package main
    
    import (
    	"fmt"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
        kafka "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/kafka/v2"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/kafka/v2/model"
        region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/kafka/v2/region"
    )
    
    func main() {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak := os.Getenv("CLOUD_SDK_AK")
        sk := os.Getenv("CLOUD_SDK_SK")
        projectId := "{project_id}"
    
        auth, err := basic.NewCredentialsBuilder().
            WithAk(ak).
            WithSk(sk).
            WithProjectId(projectId).
            SafeBuild()
    
        if err != nil {
            fmt.Println(err)
            return
        }
    
        hcClient, err := kafka.KafkaClientBuilder().
             WithRegion(region.ValueOf("<YOUR REGION>")).
             WithCredential(auth).
             SafeBuild()
    
    
        if err != nil {
            fmt.Println(err)
            return
        }
    
        client := kafka.NewKafkaClient(hcClient)
    
        request := &model.ResetMessageOffsetWithEngineRequest{}
    	request.InstanceId = "{instance_id}"
    	request.Group = "{group}"
    	timestampResetMessageOffsetReq:= int64(1571812144000)
    	request.Body = &model.ResetMessageOffsetReq{
    		Timestamp: &timestampResetMessageOffsetReq,
    		Partition: int32(0),
    		Topic: "test",
    	}
    	response, err := client.ResetMessageOffsetWithEngine(request)
    	if err == nil {
            fmt.Printf("%+v\n", response)
        } else {
            fmt.Println(err)
        }
    }
    

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Code

Description

204

Successful

Error Codes

See Error Codes.