Get a physical replication stream

Can be used by the following roles assigned at the organization, folder or cluster scope:

• CLUSTER_ADMIN
• CLUSTER_OPERATOR_WRITER
• CLUSTER_DEVELOPER

GET /api/v1/physical-replication-streams/{id}

cURL

cURL

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/physical-replication-streams/{id} \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

200

{
  "activated_at": "2006-01-03T15:04:15Z",
  "created_at": "2006-01-02T15:04:05Z",
  "failover_at": "2006-01-03T15:04:05Z",
  "id": "00000000-0000-0000-0000-000000000001",
  "primary_cluster_id": "00000000-0000-0000-0000-000000000002",
  "replicated_time": "2006-01-03T15:04:04Z",
  "retained_time": "2006-01-02T15:04:06Z",
  "standby_cluster_id": "00000000-0000-0000-0000-000000000003",
  "status": "COMPLETED"
}

PREVIEW

This endpoint is in Preview and subject to change. Refer to the API support policy for more details.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id · string · required

id is the ID of the replication stream to get.

Response

200

application/json

A successful response.

created_at · string<date-time> · required

created_at is the timestamp at which the replication stream was created.

id · string · required

id is the UUID of the replication stream.

primary_cluster_id · string · required

primary_cluster_id is the ID of the cluster that is being replicated.

standby_cluster_id · string · required

standby_cluster_id is the ID of the standby cluster that data is being replicated to.

status · enum<string> · required

status describes the desired status of the replication stream.

• STARTING: signifies that a stream is starting
• REPLICATING: signifies that the standby is receiving the primary's changes. Failover is available once the stream reports a 'replicated_time'.
• FAILING_OVER: used to trigger a failover, or to signify that a failover is occurring.
• COMPLETED: signifies that a failover is complete.
• CANCELED: signifies that a stream is canceled.

Available options: STARTING, REPLICATING, FAILING_OVER, COMPLETED, CANCELED

activated_at · string<date-time>

activated_at is the crdb system time at which failover is finalized. This may differ from the time for which failover was requested. This field will be present when a replication stream is in the COMPLETED state.

canceled_at · string<date-time>

canceled_at is the timestamp at which the replication stream was canceled.

failover_at · string<date-time>

failover_at is the time for which failover is requested. If the user sets the status to 'FAILING_OVER' but omits failover_at, the failover time will default to the latest consistent replicated time. Otherwise, the user can pick a time up to one hour in the future to schedule a failover, or a time in the past to restore the cluster to a recent state. This field will be present if the user has requested failover at a future time.

replicated_time · string<date-time>

replicated_time is the timestamp indicating the point up to which data has been replicated. The window between replicated_time and the actual time is known as replication lag. This field is absent until the standby has copied the primary's existing data. Failover is available only once it is present.

replication_lag_seconds · integer<int32>

replication_lag_seconds is the replication lag (current time minus replicated time) in seconds. This field is present whenever replicated_time is.

retained_time · string<date-time>

retained_time is the timestamp indicating the lower bound that the replication stream can failover to. This field is absent until the standby reports it.