List connectors
GET/usm/v1/connect-clusters/:connect_cluster_id/connectors
Default returns a native-compatible array of names. ?expand returns a map keyed by name. ?page_size switches to the paginated List envelope (Cloud-only), returning pagination metadata in headers rather than the response body so the native-compatible array/map shape is preserved (this differs from the inline-metadata pagination used by GET /usm/v1/connect-clusters; deliberate, see the Design Notes in the companion Confluence contract). ?show_deleted=true includes soft-deleted (DELETING) connectors.
Request
Responses
- 200
- 400
- 401
- 404
- 429
- 500
OK. Bare array of names, or the name-keyed map when ?expand is set. The next-page cursor (when ?page_size is set) is in the Link (rel="next") and X-Next-Page-Token response headers, never in the body.
Response Headers
Link
Next-page cursor, rel="next". Present only when more pages remain.
X-Next-Page-Token
Opaque cursor for the next page. Present only when more pages remain.
Bad request (malformed body, invalid page size/token)
Unauthenticated
Connector or cluster not found
Rate limited
Response Headers
Retry-After
Seconds to wait before retrying.
Internal server error
OpenAPI definition (YAML)
paths:
/usm/v1/connect-clusters/{connect_cluster_id}/connectors:
get:
x-lifecycle-stage: Early Access
tags:
- Connectors (usm/v1)
operationId: listUsmConnectV1Connectors
description: '[](#section/Versioning/API-Lifecycle-Policy)
Default returns a native-compatible array of names. `?expand` returns a map keyed by name. `?page_size`
switches to the paginated List envelope (Cloud-only), returning pagination metadata in headers
rather than the response body so the native-compatible array/map shape is preserved (this differs
from the inline-metadata pagination used by `GET /usm/v1/connect-clusters`; deliberate, see the
Design Notes in the companion Confluence contract). `?show_deleted=true` includes soft-deleted
(`DELETING`) connectors.
'
security:
- cloud-api-key: []
- global-api-key: []
- confluent-sts-access-token: []
parameters:
- name: expand
in: query
required: false
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- info
- status
- id
description: Inlines the selected views into the list response.
- name: page_size
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
description: 'Cloud-only. Presence turns on paging without changing the response body shape; the
next cursor is in the Link / X-Next-Page-Token headers. First request only.
'
- name: page_token
in: query
required: false
schema:
type: string
description: Opaque cursor taken from the previous page's Link / X-Next-Page-Token header. Follow-up
pages only.
- 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: 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. Bare array of names, or the name-keyed map when `?expand` is set. The next-page
cursor (when `?page_size` is set) is in the `Link` (rel="next") and `X-Next-Page-Token` response
headers, never in the body.
'
headers:
Link:
description: Next-page cursor, rel="next". Present only when more pages remain.
schema:
type: string
X-Next-Page-Token:
description: Opaque cursor for the next page. Present only when more pages remain.
schema:
type: string
content:
application/json:
schema:
oneOf:
- type: array
items:
type: string
example:
- s3-sink-01
- jdbc-source-02
title: usm-connect.v1.ConnectorNameList
- type: object
additionalProperties:
type: object
properties:
id:
type: object
description: The connector's identifier, in the requested `?expand=id` shape.
properties:
id:
type: string
description: The connector's identifier value.
id_type:
type: string
example: ID
description: The type/format of the identifier value.
info:
type: object
description: The connector's desired-state configuration as last accepted by Cloud.
required:
- id
- name
- type
- config
- tasks
properties:
id:
type: string
maxLength: 255
example: usmco-a1b2c3
readOnly: true
description: 'The connector''s unique Cloud-assigned ID (Cloud-only extension;
not part of native Kafka Connect''s ConnectorInfo).
'
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
- UNKNOWN
config:
type: object
description: 'Low-level connector config, native-compatible (all values strings,
dotted keys like `connector.class` — not snake_case, to match native Kafka
Connect config verbatim). Secret fields must be config-provider references
(`${provider:path:key}`). Secrets set as config-provider references are
returned as the reference on read; all other secrets are returned masked
as ****.
'
additionalProperties:
type: string
example:
connector.class: io.confluent.connect.s3.S3SinkConnector
tasks.max: '2'
topics: orders
aws.secret.access.key: ${securepass:aws:secret}
title: usm-connect.v1.ConfigMap
tasks:
type: array
description: 'The connector''s task assignments as last known at write time
(informational only, not read from the live worker); see `GET .../status`
for current task state.
'
items:
type: object
properties:
connector:
type: string
description: The name of the connector this task belongs to.
task:
type: integer
format: int32
description: The task's index.
data_cluster_scope:
type: string
description: 'Whether the connector''s data Kafka cluster (distinct from the
Connect cluster''s metadata Kafka cluster) is a Confluent Cloud cluster.
UNKNOWN is common and must be handled as a first-class value.
'
enum:
- CLOUD
- ON_PREM
- UNKNOWN
title: usm-connect.v1.ConnectorInfo
status:
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
title: usm-connect.v1.ConnectorExpansionMap
'400':
description: Bad request (malformed body, invalid page size/token)
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
'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