Skip to main content

Get restart request status

GET 
/usm/v1/connect-clusters/:connect_cluster_id/connectors/:connector_name/restart/status

Early Access

Status of the most recent restart request made via POST .../restart. Poll with backoff until a terminal status.phase (SUCCESSFUL/FAILED). Returns 404 if no restart has ever been requested for this connector, or the record has aged out of the retention window (TTL TBD) — that's not an error condition, just "nothing to report."

Request​

Responses​

OK

OpenAPI definition (YAML) 
paths:
  /usm/v1/connect-clusters/{connect_cluster_id}/connectors/{connector_name}/restart/status:
    get:
      x-lifecycle-stage: Early Access
      tags:
      - Lifecycle (usm/v1)
      operationId: readUsmConnectV1ConnectorRestartStatus
      description: '[![Early Access](https://img.shields.io/badge/Lifecycle%20Stage-Early%20Access-%2345c6e8)](#section/Versioning/API-Lifecycle-Policy)


        Status of the most recent restart request made via `POST .../restart`. Poll with backoff until
        a terminal `status.phase` (`SUCCESSFUL`/`FAILED`). Returns `404` if no restart has ever been requested
        for this connector, or the record has aged out of the retention window (TTL TBD) — that''s not
        an error condition, just "nothing to report."

        '
      security:
      - cloud-api-key: []
      - global-api-key: []
      - confluent-sts-access-token: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: 'Status of the restart requested via `POST .../restart`, backed 1:1 by the
                  reconciler''s own `RestartRequest`/`RestartStatus`: `status.phase` is `IN_PROGRESS`
                  for as long as the reconciler''s `RestartRequest.requested` stays true (unresolved);
                  once the reconciler resolves it, `RestartStatus.result` `DONE` surfaces here as `SUCCESSFUL`,
                  and `FAILED` surfaces as `FAILED` with `status.error` populated from the reconciler''s
                  own `CloudError`.

                  '
                required:
                - request
                - status
                properties:
                  request:
                    type: object
                    description: The request made to restart the connector.
                    required:
                    - connector
                    - requested_at
                    properties:
                      connector:
                        type: string
                        example: s3-sink-01
                        description: The name of the connector this restart request targets.
                      include_tasks:
                        type: boolean
                        description: Echoes the `includeTasks` query param this restart request was made
                          with.
                      only_failed:
                        type: boolean
                        description: Echoes the `onlyFailed` query param this restart request was made
                          with.
                      requested_at:
                        type: string
                        format: date-time
                        readOnly: true
                        example: '2024-02-20 15:14:19+00:00'
                        description: The time at which the request was made. The time is in UTC, ISO 8601
                          format.
                    title: usm-connect.v1.RestartRequestInfo
                  status:
                    type: object
                    required:
                    - phase
                    description: The status of the restart request.
                    properties:
                      phase:
                        type: string
                        description: 'The phase of the restart request.


                          IN_PROGRESS: The reconciler hasn''t resolved this request yet.


                          SUCCESSFUL: The reconciler resolved it with result DONE.


                          FAILED: The reconciler resolved it with result FAILED; see `error`.'
                        enum:
                        - IN_PROGRESS
                        - SUCCESSFUL
                        - FAILED
                      error:
                        allOf:
                        - type: object
                          description: Mirrors the reconciler's own `CloudError` proto 1:1.
                          required:
                          - error_type
                          - error_message
                          properties:
                            error_type:
                              type: string
                              description: Mirrors the reconciler's internal `CloudError.ErrorType` proto
                                1:1.
                              enum:
                              - ERROR_UNSPECIFIED
                              - VALIDATION_ERROR
                              - CONNECTION_ERROR
                              - RUNTIME_ERROR
                              - OPERATION_EXPIRED
                              - INTERNAL_ERROR
                            error_message:
                              type: string
                              description: 'Human-readable detail, sourced from the on-prem connector
                                or the reconciliation pipeline. Mirrors the reconciler''s own `CloudError.error_message`
                                1:1.

                                '
                          title: usm-connect.v1.CloudError
                        description: Present only when `phase` is `FAILED`.
                title: usm-connect.v1.RestartRequestStatus
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                type: object
                description: 'Flat error envelope, native-compatible: native Kafka Connect clients only
                  need error_code + message; reason and request_id are backward-compatible extensions
                  for programmatic handling. Deliberately not this repo''s usual JSON:API {errors:[...]}
                  shape (same divergence connect/openapi.yaml already made) — see the companion Confluence
                  contract''s Design Notes for the full rationale.

                  '
                required:
                - error_code
                - message
                properties:
                  error_code:
                    type: integer
                    format: int32
                    description: Mirrors the HTTP status.
                  reason:
                    type: string
                    description: Optional machine-readable key. Not exhaustive; may grow without breaking
                      the envelope.
                    enum:
                    - INVALID_REQUEST_BODY
                    - MISSING_REQUIRED_FIELD
                    - INVALID_PAGE_SIZE
                    - INVALID_PAGE_TOKEN
                    - UNAUTHENTICATED
                    - AUTHORIZATION_FAILED
                    - CONNECTOR_NOT_FOUND
                    - CONNECT_CLUSTER_NOT_FOUND
                    - REQUEST_NOT_FOUND
                    - CONNECTOR_ALREADY_EXISTS
                    - CONNECTOR_ALREADY_DELETING
                    - CONNECTOR_MODIFIED
                    - MANAGEABILITY_DISABLED
                    - REBALANCE_IN_PROGRESS
                    - RESTART_ALREADY_IN_PROGRESS
                    - SECRET_MUST_BE_REFERENCE
                    - INVALID_CONNECTOR_CONFIG
                    - RATE_LIMITED
                    - INTERNAL_ERROR
                    - CONNECT_CLUSTER_UNREACHABLE
                  message:
                    type: string
                    description: Human-readable error message.
                  request_id:
                    type: string
                    description: Optional trace id; mirrors X-Request-Id.
                title: usm-connect.v1.ErrorEnvelope
        '404':
          description: Connector or cluster not found
          content:
            application/json:
              schema:
                type: object
                description: 'Flat error envelope, native-compatible: native Kafka Connect clients only
                  need error_code + message; reason and request_id are backward-compatible extensions
                  for programmatic handling. Deliberately not this repo''s usual JSON:API {errors:[...]}
                  shape (same divergence connect/openapi.yaml already made) — see the companion Confluence
                  contract''s Design Notes for the full rationale.

                  '
                required:
                - error_code
                - message
                properties:
                  error_code:
                    type: integer
                    format: int32
                    description: Mirrors the HTTP status.
                  reason:
                    type: string
                    description: Optional machine-readable key. Not exhaustive; may grow without breaking
                      the envelope.
                    enum:
                    - INVALID_REQUEST_BODY
                    - MISSING_REQUIRED_FIELD
                    - INVALID_PAGE_SIZE
                    - INVALID_PAGE_TOKEN
                    - UNAUTHENTICATED
                    - AUTHORIZATION_FAILED
                    - CONNECTOR_NOT_FOUND
                    - CONNECT_CLUSTER_NOT_FOUND
                    - REQUEST_NOT_FOUND
                    - CONNECTOR_ALREADY_EXISTS
                    - CONNECTOR_ALREADY_DELETING
                    - CONNECTOR_MODIFIED
                    - MANAGEABILITY_DISABLED
                    - REBALANCE_IN_PROGRESS
                    - RESTART_ALREADY_IN_PROGRESS
                    - SECRET_MUST_BE_REFERENCE
                    - INVALID_CONNECTOR_CONFIG
                    - RATE_LIMITED
                    - INTERNAL_ERROR
                    - CONNECT_CLUSTER_UNREACHABLE
                  message:
                    type: string
                    description: Human-readable error message.
                  request_id:
                    type: string
                    description: Optional trace id; mirrors X-Request-Id.
                title: usm-connect.v1.ErrorEnvelope
        '429':
          description: Rate limited
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                description: 'Flat error envelope, native-compatible: native Kafka Connect clients only
                  need error_code + message; reason and request_id are backward-compatible extensions
                  for programmatic handling. Deliberately not this repo''s usual JSON:API {errors:[...]}
                  shape (same divergence connect/openapi.yaml already made) — see the companion Confluence
                  contract''s Design Notes for the full rationale.

                  '
                required:
                - error_code
                - message
                properties:
                  error_code:
                    type: integer
                    format: int32
                    description: Mirrors the HTTP status.
                  reason:
                    type: string
                    description: Optional machine-readable key. Not exhaustive; may grow without breaking
                      the envelope.
                    enum:
                    - INVALID_REQUEST_BODY
                    - MISSING_REQUIRED_FIELD
                    - INVALID_PAGE_SIZE
                    - INVALID_PAGE_TOKEN
                    - UNAUTHENTICATED
                    - AUTHORIZATION_FAILED
                    - CONNECTOR_NOT_FOUND
                    - CONNECT_CLUSTER_NOT_FOUND
                    - REQUEST_NOT_FOUND
                    - CONNECTOR_ALREADY_EXISTS
                    - CONNECTOR_ALREADY_DELETING
                    - CONNECTOR_MODIFIED
                    - MANAGEABILITY_DISABLED
                    - REBALANCE_IN_PROGRESS
                    - RESTART_ALREADY_IN_PROGRESS
                    - SECRET_MUST_BE_REFERENCE
                    - INVALID_CONNECTOR_CONFIG
                    - RATE_LIMITED
                    - INTERNAL_ERROR
                    - CONNECT_CLUSTER_UNREACHABLE
                  message:
                    type: string
                    description: Human-readable error message.
                  request_id:
                    type: string
                    description: Optional trace id; mirrors X-Request-Id.
                title: usm-connect.v1.ErrorEnvelope
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                description: 'Flat error envelope, native-compatible: native Kafka Connect clients only
                  need error_code + message; reason and request_id are backward-compatible extensions
                  for programmatic handling. Deliberately not this repo''s usual JSON:API {errors:[...]}
                  shape (same divergence connect/openapi.yaml already made) — see the companion Confluence
                  contract''s Design Notes for the full rationale.

                  '
                required:
                - error_code
                - message
                properties:
                  error_code:
                    type: integer
                    format: int32
                    description: Mirrors the HTTP status.
                  reason:
                    type: string
                    description: Optional machine-readable key. Not exhaustive; may grow without breaking
                      the envelope.
                    enum:
                    - INVALID_REQUEST_BODY
                    - MISSING_REQUIRED_FIELD
                    - INVALID_PAGE_SIZE
                    - INVALID_PAGE_TOKEN
                    - UNAUTHENTICATED
                    - AUTHORIZATION_FAILED
                    - CONNECTOR_NOT_FOUND
                    - CONNECT_CLUSTER_NOT_FOUND
                    - REQUEST_NOT_FOUND
                    - CONNECTOR_ALREADY_EXISTS
                    - CONNECTOR_ALREADY_DELETING
                    - CONNECTOR_MODIFIED
                    - MANAGEABILITY_DISABLED
                    - REBALANCE_IN_PROGRESS
                    - RESTART_ALREADY_IN_PROGRESS
                    - SECRET_MUST_BE_REFERENCE
                    - INVALID_CONNECTOR_CONFIG
                    - RATE_LIMITED
                    - INTERNAL_ERROR
                    - CONNECT_CLUSTER_UNREACHABLE
                  message:
                    type: string
                    description: Human-readable error message.
                  request_id:
                    type: string
                    description: Optional trace id; mirrors X-Request-Id.
                title: usm-connect.v1.ErrorEnvelope
      parameters:
      - name: connect_cluster_id
        in: path
        required: true
        schema:
          type: string
          example: usmcc-abc123
        description: The ID of the Connect cluster the connector runs on, as returned by GET /usm/v1/connect-clusters.
      - name: connector_name
        in: path
        required: true
        schema:
          type: string
          example: s3-sink-01
        description: The connector's unique name within its environment.
      - name: environment
        in: query
        required: true
        schema:
          type: string
          example: env-12345
        description: 'Required on every connector and cluster-scoped call, consistent with the existing
          USM cluster GET/List endpoints in usm/minispec.yaml. A missing value is rejected.

          '
      servers:
      - url: https://api.confluent.cloud
        description: Confluent Cloud API