Request a Replica Set Secondary Step Up

Note

Groups and projects are synonymous terms. Your {PROJECT-ID} is the same as your project ID. For existing groups, your group/project ID remains the same. This page uses the more familiar term group when referring to descriptions. The endpoint remains as stated in the document.

Use this endpoint to request that a specific secondary of a replica set step up to become primary. Ops Manager freezes the other electable secondaries so that the target process, not another member, wins the election. The target host's Automation Agent runs the freeze and step-down procedure on its next check-in.

If the target process is not an electable secondary when the agent runs the job, for example because it is already primary, or is an arbiter, hidden, or non-voting member, the job fails with a descriptive message.

Base URL: https://{OPSMANAGER-HOST}:{PORT}/api/public/v1.0

Resource

POST /groups/{GROUP-ID}/replicaSets/{RS-ID}/process/{HOST-PORT}:stepUp

Required Roles

The API key that makes this request must have the Project Automation Admin role.

Request Path Parameters

Name	Type	Necessity	Description
GROUP-ID	string	Required	Unique 24-hexadecimal digit string that identifies your project.
RS-ID	string	Required	Name of the replica set that contains the target process.
HOST-PORT	string	Required	Target process, as `hostname:port`. This process must currently be an active, electable secondary.

Request Query Parameters

The following query parameters are optional:

Name	Type	Necessity	Description	Default
pretty	boolean	Optional	Flag indicating whether the response body is in a prettyprint format.	`false`
envelope	boolean	Optional	Flag that indicates whether to wrap the response in an envelope. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. For endpoints that return one result, the response body includes: `status`: HTTP response code `content`: Expected response body	`false`

Request Body Parameters

The request body accepts the following optional tunables. If you send an empty body, use {}.

Name	Type	Description	Default
stepDownSecs	integer	Number of seconds the outgoing primary remains ineligible for re-election. Must be greater than `0`.	`60`
secondaryCatchUpPeriodSecs	integer	Number of seconds to wait for a lagging secondary to catch up before the primary steps down. Must be greater than or equal to `0`. If you omit this field, `mongod` applies its own default.	None
freezeSecs	integer	Number of seconds Ops Manager freezes the other electable secondaries so that the target wins the election. Must be greater than `0` and greater than or equal to `stepDownSecs`.	The greater of `120` and `stepDownSecs`
expiresAfterSeconds	integer	Number of seconds the request stays queued for an Automation Agent to pick up before the job expires. Must be greater than `0`.	The greater of `300` and `freezeSecs`

Important

During the freeze window, every other electable secondary is frozen and cannot stand for election. Keep freezeSecs as short as your environment allows. If the target host becomes unreachable during the freeze, the replica set can be left without a primary until the freeze expires.

Response

Ops Manager returns 202 Accepted with a Location header that points to the get one re-election job endpoint, and the re-election job document in the response body.

Name	Type	Description
id	string	Unique 24-hexadecimal digit string that identifies the re-election job.
groupId	string	Unique 24-hexadecimal digit string that identifies the project.
action	string	Action that this job performs. Returns `STEP_UP`.
replicaSetName	string	Name of the target replica set.
hostname	string	Hostname of the target process.
port	integer	Port of the target process.
status	string	Status of the job. Returns one of the following values: `QUEUED`, `RUNNING`, `COMPLETED`, `FAILED`, or `EXPIRED`.
noOp	boolean	Flag that indicates whether the operation completed as a no-op.
message	string	Human-readable detail about the job. Ops Manager populates this field after the agent reports a result.
created	string	Timestamp, in ISO 8601 UTC format, when Ops Manager created the job.
lastUpdated	string	Timestamp, in ISO 8601 UTC format, when Ops Manager last updated the job.
expires	string	Timestamp, in ISO 8601 UTC format, after which an Automation Agent no longer picks up this job.

Example Request

1 curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
2      --header "Accept: application/json" \
3      --header "Content-Type: application/json" \
4      --include \
5      --request POST "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/replicaSets/{RS-ID}/process/{HOST-PORT}:stepUp?pretty=true" \
6      --data '{
7        "stepDownSecs": 60,
8        "freezeSecs": 120
9      }'

Example Response

Response Header

HTTP/1.1 202 Accepted
Vary: Accept-Encoding
Content-Type: application/json
Location: https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/replicaSets/{RS-ID}/reElectionJobs/{REELECTION-JOB-ID}
Strict-Transport-Security: max-age=300
Date: {dateInUnixFormat}
Connection: keep-alive
Content-Length: {requestLengthInBytes}
X-MongoDB-Service-Version: gitHash={gitHash}; versionString={ApplicationVersion}

Response Body

1 {
2   "id": "665a1234567890abcdef1234",
3   "groupId": "5c8100bcf2a30b12ff88258f",
4   "action": "STEP_UP",
5   "replicaSetName": "rs0",
6   "hostname": "node2.example.com",
7   "port": 27017,
8   "status": "QUEUED",
9   "noOp": false,
10   "message": null,
11   "created": "2026-08-11T05:37:59Z",
12   "lastUpdated": "2026-08-11T05:37:59Z",
13   "expires": "2026-08-11T05:39:59Z"
14 }

Response Codes

HTTP Status	Error Code	Description
202	--	Request accepted. Returns the re-election job document.
400	INVALID_PARAMETER	A tunable is out of range, or `freezeSecs` is less than `stepDownSecs`.
400	AUTOMATION_AGENT_VERSION_NOT_SUPPORTED	The target host's Automation Agent is older than `109.0.0.9226-1`.
401	USER_UNAUTHORIZED	The API key does not have the `Project Automation Admin` role.
401	USER_CANNOT_ACCESS_ORG	The caller is outside the project's organization.
404	AUTOMATION_CONFIG_NOT_FOUND	The project has no published automation configuration.
404	CLUSTER_NOT_FOUND	`RS-ID` does not match a replica set in the project's deployment.
404	PROCESS_NOT_IN_CLUSTER	`HOST-PORT` is not a member of the named replica set.
409	REELECTION_AGENT_NOT_RESPONDING	The target host's Automation Agent has not pinged Ops Manager recently.
409	REELECTION_ALREADY_IN_PROGRESS	A re-election job is already queued or running for this replica set.

Back

Step Down a Primary

Get One

1	curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
2	--header "Accept: application/json" \
3	--header "Content-Type: application/json" \
4	--include \
5	--request POST "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/replicaSets/{RS-ID}/process/{HOST-PORT}:stepUp?pretty=true" \
6	--data '{
7	"stepDownSecs": 60,
8	"freezeSecs": 120
9	}'

1	{
2	"id": "665a1234567890abcdef1234",
3	"groupId": "5c8100bcf2a30b12ff88258f",
4	"action": "STEP_UP",
5	"replicaSetName": "rs0",
6	"hostname": "node2.example.com",
7	"port": 27017,
8	"status": "QUEUED",
9	"noOp": false,
10	"message": null,
11	"created": "2026-08-11T05:37:59Z",
12	"lastUpdated": "2026-08-11T05:37:59Z",
13	"expires": "2026-08-11T05:39:59Z"
14	}