Help Center/Distributed Message Service for Kafka/API Reference/APIs V2 (Recommended)/Topic Management/Initiating Partition Reassignment for a Kafka Instance
Updated on 2026-03-16 GMT+08:00
View PDF

Initiating Partition Reassignment for a Kafka Instance

Function

This API is used to submit a partition reassignment task for a Kafka instance. If the task is successfully submitted, its job ID is returned.

Calling Method

For details, see Calling APIs.

URI

POST /v2/{project_id}/kafka/instances/{instance_id}/reassign

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain it, see Obtaining a Project ID.

instance_id

Yes

String

Instance ID.

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

reassignments

Yes

Array of PartitionReassignEntity objects

Partition reassignment plan.

throttle

No

Integer

Partition reassignment threshold.

is_schedule

No

Boolean

Definition

Whether to schedule the task. If no, the is_schedule and execute_at fields can be left empty. If yes, is_schedule is true and execute_at must be specified.

Constraints

N/A

execute_at

No

Long

Definition

Schedule time. The value is a UNIX timestamp, in ms.

Constraints

N/A

time_estimate

No

Boolean

Definition

Set true to perform time estimation tasks and false to perform partition reassignment tasks.

Constraints

N/A

Table 3 PartitionReassignEntity

Parameter

Mandatory

Type

Description

topic

Yes

String

Topic name

brokers

No

Array of integers

List of brokers to which partitions are reassigned. This parameter is mandatory in automatic assignment.

replication_factor

No

Integer

Replication factor, which can be specified in automatic assignment.

assignment

No

Array of TopicAssignment objects

Manually specified assignment plan. The brokers parameter and this parameter cannot be empty at the same time.

Table 4 TopicAssignment

Parameter

Mandatory

Type

Description

partition

No

Integer

Partition number in manual assignment.

partition_brokers

No

Array of integers

List of brokers to be assigned to a partition in manual assignment.

Response Parameters

Status code: 200

Table 5 Response body parameters

Parameter

Type

Description

job_id

String

Task ID. Only job_id is returned for a partition reassignment task.

reassignment_time

Integer

Estimated time, in seconds. Only reassignment_time is returned for a time estimation task.

Example Requests

POST https://{endpoint}/v2/kafka/{project_id}/instances/{instance_id}/reassign

{
  "reassignments" : [ {
    "topic" : "topic-1513476102",
    "brokers" : [ 0, 1, 2 ],
    "replication_factor" : 3,
    "assignment" : [ {
      "partition" : 0,
      "partition_brokers" : [ 0, 1, 2 ]
    }, {
      "partition" : 1,
      "partition_brokers" : [ 1, 2, 0 ]
    }, {
      "partition" : 2,
      "partition_brokers" : [ 2, 0, 1 ]
    } ]
  }, {
    "topic" : "topic-1513558717",
    "brokers" : [ 0, 1, 4 ],
    "replication_factor" : 3,
    "assignment" : [ {
      "partition" : 0,
      "partition_brokers" : [ 0, 1, 2 ]
    }, {
      "partition" : 1,
      "partition_brokers" : [ 1, 2, 0 ]
    }, {
      "partition" : 2,
      "partition_brokers" : [ 2, 0, 1 ]
    } ]
  } ],
  "throttle" : 10000000,
  "time_estimate" : false
}

Example Responses

Status code: 200

Partition assignment submitted (The duration is returned for an estimation task.).

{
  "job_id" : "8a2c259182ab0e9d0182ab1882560009",
  "reassignment_time" : 10
}

Status Codes

Status Code

Description

200

Partition assignment submitted (The duration is returned for an estimation task.).

Error Codes

See Error Codes.

Parent Topic: Topic Management