Request a Replica Set Primary Step Down

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 the current primary of a replica set step down, triggering a new election. Ops Manager queues a background job for the target host's Automation Agent to run on its next check-in.

If the target process is not the writable primary when the agent runs the job, the job completes as a no-op rather than failing. After the primary steps down, it remains ineligible for re-election for the duration specified by stepDownSecs.

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

Resource

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

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 the replica set's primary.

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 stepped-down 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
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`.	`300`

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_DOWN`.
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. Returns `true` if the target process was already a secondary when the agent ran the job.
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}:stepDown?pretty=true" \
6      --data '{
7        "stepDownSecs": 60,
8        "secondaryCatchUpPeriodSecs": 10
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_DOWN",
5   "replicaSetName": "rs0",
6   "hostname": "node1.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:42: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 the request body includes `freezeSecs`.
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

Re-Election Jobs

Step Up a Secondary

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}:stepDown?pretty=true" \
6	--data '{
7	"stepDownSecs": 60,
8	"secondaryCatchUpPeriodSecs": 10
9	}'

1	{
2	"id": "665a1234567890abcdef1234",
3	"groupId": "5c8100bcf2a30b12ff88258f",
4	"action": "STEP_DOWN",
5	"replicaSetName": "rs0",
6	"hostname": "node1.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:42:59Z"
14	}