Skip to main content

Get connector status (the error-bearing read)

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

Early Access

Native core fields (connector, tasks[], plain trace) plus Cloud extensions. Because execution happens out-of-band from the write call, this is where runtime errors, deferred config-validation failures, and failed-management-operation errors all surface (never as HTTP errors on the accepting call). By default a DELETING connector 404s; pass ?show_deleted=true to read its status and the deletion error in cloud_error while it exists.

Request​

Responses​

OK

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


        Native core fields (`connector`, `tasks[]`, plain `trace`) plus Cloud extensions. Because execution
        happens out-of-band from the write call, this is where runtime errors, deferred config-validation
        failures, and failed-management-operation errors all surface (never as HTTP errors on the accepting
        call). By default a `DELETING` connector 404s; pass `?show_deleted=true` to read its status and
        the deletion error in `cloud_error` while it exists.

        '
      security:
      - cloud-api-key: []
      - global-api-key: []
      - confluent-sts-access-token: []
      parameters:
      - name: show_deleted
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: When true, includes soft-deleted (DELETING) connectors/records in the response. Default
          false hides them (on-prem parity).
      - 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.

          '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Native core fields (always present) plus Cloud/GA extensions.
                required:
                - name
                - type
                - connector
                - tasks
                properties:
                  name:
                    type: string
                    description: The connector's unique name within its environment.
                  type:
                    type: string
                    description: Whether the connector is a source or sink.
                    enum:
                    - SOURCE
                    - SINK
                  connector:
                    allOf:
                    - type: object
                      description: Runtime state of a connector or task process.
                      properties:
                        state:
                          type: string
                          description: The process's current run state.
                          enum:
                          - RUNNING
                          - PAUSED
                          - FAILED
                          - UNASSIGNED
                          - RESTARTING
                        worker_id:
                          type: string
                          description: 'Identifier of the on-prem worker process currently running this
                            connector/task (native Kafka Connect field, not a Cloud resource relationship).

                            '
                        trace:
                          type: string
                          description: Plain stack trace; present only when state is FAILED.
                      title: usm-connect.v1.EntityState
                    description: The current runtime state of the connector process itself (as opposed
                      to its tasks).
                  tasks:
                    type: array
                    description: The current runtime state of each task.
                    items:
                      allOf:
                      - type: object
                        properties:
                          id:
                            type: integer
                            format: int32
                      - type: object
                        description: Runtime state of a connector or task process.
                        properties:
                          state:
                            type: string
                            description: The process's current run state.
                            enum:
                            - RUNNING
                            - PAUSED
                            - FAILED
                            - UNASSIGNED
                            - RESTARTING
                          worker_id:
                            type: string
                            description: 'Identifier of the on-prem worker process currently running this
                              connector/task (native Kafka Connect field, not a Cloud resource relationship).

                              '
                          trace:
                            type: string
                            description: Plain stack trace; present only when state is FAILED.
                        title: usm-connect.v1.EntityState
                  cloud_status:
                    type: string
                    description: The connector's aggregate lifecycle status.
                    enum:
                    - UNKNOWN
                    - PROVISIONING
                    - RUNNING
                    - DEGRADED
                    - FAILED
                    - PAUSED
                    - STOPPED
                    - DELETING
                    - DELETED
                    - RESTARTING
                  cloud_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
                    nullable: true
                    description: 'The error hit while making the last mutation call, mirroring the reconciler''s
                      own `CloudError` store 1:1. Absent/null when there''s nothing wrong. (The UI''s
                      own parsed-stack-trace rendering, formerly `errors_from_trace`, is served through
                      a separate, undocumented field — not part of this API''s public contract.)

                      '
                  plugin_lifecycle:
                    type: string
                    description: Confluent-managed lifecycle stage of the connector plugin/class currently
                      in use.
                    enum:
                    - ACTIVE
                    - DEPRECATED
                    - END_OF_LIFE
                title: usm-connect.v1.Status
        '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
      servers:
      - url: https://api.confluent.cloud
        description: Confluent Cloud API