---
title: "List all virtual clusters"
url: "https://nov18-dev.movespot.fyi/apis/konnect-control-planes-configuration-for-event-gateways-1/versions/f4366232-3186-4be9-93bd-be3e4b16fb19/operations/list-event-gateway-virtual-clusters"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-control-planes-configuration-for-event-gateways-1/versions/f4366232-3186-4be9-93bd-be3e4b16fb19.md

# List all virtual clusters

`GET` `/event-gateways/{gatewayId}/virtual-clusters`

Operation ID: `list-event-gateway-virtual-clusters`

Returns a paginated list of virtual clusters associated with the specified Event Gateway.

## Path parameters

- `gatewayId` (string, uuid, required) - The UUID of your Gateway.

## Query parameters

- `page[size]` (integer, optional) - The maximum number of items to include per page. The last page of a collection may include fewer items.
- `page[after]` (string, optional) - Request the next page of data, starting with the item after this parameter.
- `filter` (object, optional) - Filter documents returned in the response.

## Responses

- `200` - A paginated list response for a collection of virtual clusters.
- `401` - Unauthorized
- `403` - Forbidden

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Konnect Control Planes Configuration for Event Gateways
  version: 1.0.0
servers:
  - url: https://us.api.konghq.com/v1
    description: United-States Production region
  - url: https://eu.api.konghq.com/v1
    description: Europe Production region
  - url: https://au.api.konghq.com/v1
    description: Australia Production region
  - url: https://me.api.konghq.com/v1
    description: Middle-East Production region
  - url: https://in.api.konghq.com/v1
    description: India Production region
  - url: https://sg.api.konghq.com/v1
    description: Singapore Production region
paths:
  /event-gateways/{gatewayId}/virtual-clusters:
    parameters:
      - $ref: "#/components/parameters/gatewayId"
    get:
      operationId: list-event-gateway-virtual-clusters
      summary: List all virtual clusters
      description: Returns a paginated list of virtual clusters associated with the
        specified Event Gateway.
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageAfter"
        - name: filter
          in: query
          description: Filter documents returned in the response.
          required: false
          schema:
            type: object
            properties:
              backend_cluster_id:
                $ref: "#/components/schemas/StringFieldEqualsFilter"
              name:
                $ref: "#/components/schemas/StringFieldContainsFilter"
          style: deepObject
      responses:
        "200":
          $ref: "#/components/responses/ListVirtualClustersResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      tags:
        - Event Gateway Virtual Clusters
security:
  - personalAccessToken: []
  - systemAccountAccessToken: []
components:
  parameters:
    gatewayId:
      name: gatewayId
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 9524ec7d-36d9-465d-a8c5-83a3c9390458
      description: The UUID of your Gateway.
    PageSize:
      name: page[size]
      description: The maximum number of items to include per page. The last page of a
        collection may include fewer items.
      required: false
      in: query
      allowEmptyValue: true
      schema:
        type: integer
        example: 10
    PageAfter:
      name: page[after]
      description: Request the next page of data, starting with the item after this
        parameter.
      required: false
      in: query
      allowEmptyValue: true
      schema:
        type: string
        example: ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ
  schemas:
    StringFieldEqualsFilter:
      description: Filters on the given string field value by exact match.
      properties:
        eq:
          type: string
      title: StringFieldEqualsFilter
      x-examples:
        example-1: equals-some-value
        example-2:
          eq: some-value
    StringFieldContainsFilter:
      description: Filters on the given string field value by fuzzy match.
      type: object
      properties:
        contains:
          type: string
      additionalProperties: false
      required:
        - contains
      title: StringFieldContainsFilter
      x-examples:
        example-1:
          contains: some-value
    CursorMeta:
      description: Pagination metadata.
      type: object
      properties:
        page:
          $ref: "#/components/schemas/CursorMetaPage"
      required:
        - page
    VirtualCluster:
      description: A representation of a Kafka cluster that maps to a backend cluster.
      type: object
      properties:
        id:
          description: The unique identifier of the virtual cluster.
          type: string
          format: uuid
        description:
          description: A human-readable description of the virtual cluster.
          type: string
          default: ""
          maxLength: 512
        destination:
          $ref: "#/components/schemas/BackendClusterReference"
        authentication:
          $ref: "#/components/schemas/VirtualClusterAuthenticationSensitiveDataAwareSchem\
            es"
        namespace:
          $ref: "#/components/schemas/VirtualClusterNamespace"
        name:
          $ref: "#/components/schemas/VirtualClusterName"
        dns_label:
          $ref: "#/components/schemas/VirtualClusterDNSLabel"
        acl_mode:
          $ref: "#/components/schemas/VirtualClusterACLMode"
        labels:
          $ref: "#/components/schemas/Labels"
        created_at:
          $ref: "#/components/schemas/CreatedAt"
        updated_at:
          $ref: "#/components/schemas/UpdatedAt"
      additionalProperties: false
      required:
        - id
        - name
        - dns_label
        - destination
        - authentication
        - acl_mode
        - created_at
        - updated_at
    UnauthorizedError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          properties:
            status:
              example: 401
            title:
              example: Unauthorized
            type:
              example: https://httpstatuses.com/401
            instance:
              example: kong:trace:1234567890
            detail:
              example: Invalid credentials
    ForbiddenError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          properties:
            status:
              example: 403
            title:
              example: Forbidden
            type:
              example: https://httpstatuses.com/403
            instance:
              example: kong:trace:1234567890
            detail:
              example: Forbidden
    CursorMetaPage:
      type: object
      properties:
        first:
          description: URI to the first page
          type: string
          format: path
        last:
          description: URI to the last page
          type: string
          format: path
        next:
          description: URI to the next page
          type: string
          format: path
          nullable: true
        previous:
          description: URI to the previous page
          type: string
          format: path
          nullable: true
        size:
          description: Requested page size
          type: number
          example: 10
      required:
        - size
        - next
        - previous
    BackendClusterReference:
      description: The backend cluster associated with the virtual cluster.
      type: object
      properties:
        id:
          description: The unique identifier of the backend cluster.
          type: string
          format: uuid
        name:
          $ref: "#/components/schemas/BackendClusterName"
      additionalProperties: false
      required:
        - id
        - name
    VirtualClusterAuthenticationSensitiveDataAwareSchemes:
      description: |
        How to handle authentication from clients.

        It tries to authenticate with every rule sequentially one by one.
        It succeeds on the first match, and fails if no rule matches.
      type: array
      items:
        $ref: "#/components/schemas/VirtualClusterAuthenticationSensitiveDataAwareSchem\
          e"
      minItems: 1
    VirtualClusterNamespace:
      description: >
        Namespace allows to implement multitenancy using a single backend
        cluster.

        It allows to either hide or enforce a static prefix on resources
        (topics, consumer group IDs, transaction IDs).
      type: object
      properties:
        mode:
          description: >
            * hide_prefix - the configured prefix is hidden from clients for
            topics and IDs when reading.
              Created resources are written with the prefix on the backend cluster.
            * enforce_prefix - the configured prefix remains visible to clients.
              Created resources must include the prefix or the request will fail.
          type: string
          enum:
            - hide_prefix
            - enforce_prefix
        prefix:
          description: >
            The namespace is differentiated by this chosen prefix.

            For example, if the prefix is set to "analytics_" the topic named
            "analytics_user_clicks" is available to the clients

            of the virtual cluster. Topics without the prefix will be ignored
            unless added via `additional.topics`.
          type: string
          minLength: 1
        additional:
          $ref: "#/components/schemas/VirtualClusterNamespaceAdditionalProperties"
      required:
        - mode
        - prefix
    VirtualClusterName:
      description: The name of the virtual cluster.
      type: string
      maxLength: 255
      minLength: 1
      x-unicode-pattern: ^[\p{L}\p{N}][\p{L}\p{N} _\-\.:/+']*[\p{L}\p{N}]$
    VirtualClusterDNSLabel:
      description: >-
        The DNS label used in the bootstrap server URL to identify the virtual
        cluster when using SNI routing.

        The format follows the RFC1035: 1-63 chars, lowercase alphanumeric or
        '-', must start and end with an alphanumeric character.
      type: string
      example: vcluster-1
      maxLength: 63
      minLength: 1
      pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
    VirtualClusterACLMode:
      description: >
        Configures whether or not ACL policies are enforced on the gateway.

        - `enforce_on_gateway` means the gateway enforces its own ACL policies
        for this virtual cluster
          and does not forward ACL-related commands to the backend cluster.
          Note that if there are no ACL policies configured, all access is denied.
        - `passthrough` tells the gateway to forward all ACL-related commands.
      type: string
      enum:
        - enforce_on_gateway
        - passthrough
    Labels:
      description: >
        Labels store metadata of an entity that can be used for filtering an
        entity list or for searching across entity types. 


        Keys must be of length 1-63 characters, and cannot start with "kong",
        "konnect", "mesh", "kic", or "_".
      type: object
      example:
        env: test
      additionalProperties:
        type: string
        pattern: ^[a-z0-9A-Z]{1}([a-z0-9A-Z-._]*[a-z0-9A-Z]+)?$
        minLength: 1
        maxLength: 63
      maxProperties: 50
      title: Labels
    CreatedAt:
      description: An ISO-8601 timestamp representation of entity creation date.
      type: string
      format: date-time
      example: 2022-11-04T20:10:06.927Z
      readOnly: true
    UpdatedAt:
      description: An ISO-8601 timestamp representation of entity update date.
      type: string
      format: date-time
      example: 2022-11-04T20:10:06.927Z
      readOnly: true
    BaseError:
      description: standard error
      type: object
      properties:
        status:
          description: >
            The HTTP status code of the error. Useful when passing the response

            body to child properties in a frontend UI. Must be returned as an
            integer.
          type: integer
          readOnly: true
        title:
          description: |
            A short, human-readable summary of the problem. It should not
            change between occurences of a problem, except for localization.
            Should be provided as "Sentence case" for direct use in the UI.
          type: string
          readOnly: true
        type:
          description: The error type.
          type: string
          readOnly: true
        instance:
          description: |
            Used to return the correlation ID back to the user, in the format
            kong:trace:<correlation_id>. This helps us find the relevant logs
            when a customer reports an issue.
          type: string
          readOnly: true
        detail:
          description: >
            A human readable explanation specific to this occurence of the
            problem.

            This field may contain request/entity data to help the user
            understand

            what went wrong. Enclose variable values in square brackets. Should
            be

            provided as "Sentence case" for direct use in the UI.
          type: string
          readOnly: true
      required:
        - status
        - title
        - instance
        - detail
      title: Error
    BackendClusterName:
      description: The unique name of the backend cluster.
      type: string
      maxLength: 255
      minLength: 1
      x-unicode-pattern: ^[\p{L}\p{N}][\p{L}\p{N} _\-\.:/+']*[\p{L}\p{N}]$
    VirtualClusterAuthenticationSensitiveDataAwareScheme:
      discriminator:
        propertyName: type
        mapping:
          anonymous: "#/components/schemas/VirtualClusterAuthenticationAnonymous"
          sasl_plain: "#/components/schemas/VirtualClusterAuthenticationSaslPlainSensitiv\
            eDataAware"
          sasl_scram: "#/components/schemas/VirtualClusterAuthenticationSaslScram"
          oauth_bearer: "#/components/schemas/VirtualClusterAuthenticationOauthBearer"
          client_certificate: "#/components/schemas/VirtualClusterAuthenticationClientCertificate"
      oneOf:
        - $ref: "#/components/schemas/VirtualClusterAuthenticationAnonymous"
        - $ref: "#/components/schemas/VirtualClusterAuthenticationSaslPlainSensitiveDataA\
            ware"
        - $ref: "#/components/schemas/VirtualClusterAuthenticationSaslScram"
        - $ref: "#/components/schemas/VirtualClusterAuthenticationOauthBearer"
        - $ref: "#/components/schemas/VirtualClusterAuthenticationClientCertificate"
    VirtualClusterNamespaceAdditionalProperties:
      type: object
      properties:
        topics:
          description: >
            Additional backend topics to expose even if they don't match the
            namespace prefix.

            The topics are not affected by the hide/enforce prefix mode.

            If the client tries to create a topic that matches this list, the
            request is rejected.
          type: array
          items:
            $ref: "#/components/schemas/VirtualClusterNamespaceTopicSelector"
        consumer_groups:
          description: >
            Consumer group IDs to expose even if they don't start with the
            namespace prefix.
          type: array
          items:
            $ref: "#/components/schemas/VirtualClusterNamespaceIdSelector"
    VirtualClusterAuthenticationAnonymous:
      type: object
      properties:
        type:
          type: string
          enum:
            - anonymous
          x-terraform-transform-const: true
      required:
        - type
    VirtualClusterAuthenticationSaslPlainSensitiveDataAware:
      description: SASL/PLAIN authentication scheme for the virtual cluster.
      type: object
      properties:
        type:
          type: string
          enum:
            - sasl_plain
          x-terraform-transform-const: true
        mediation:
          description: The mediation type for SASL/PLAIN authentication.
          type: string
          enum:
            - passthrough
            - terminate
        principals:
          description: List of principals to be able to authenticate with, used with
            `terminate` mediation.
          type: array
          items:
            $ref: "#/components/schemas/VirtualClusterAuthenticationPrincipalSensitiveDataA\
              ware"
      additionalProperties: false
      required:
        - type
        - mediation
    VirtualClusterAuthenticationSaslScram:
      description: SASL/SCRAM authentication scheme for the virtual cluster.
      type: object
      properties:
        type:
          type: string
          enum:
            - sasl_scram
          x-terraform-transform-const: true
        algorithm:
          description: The algorithm used for SASL/SCRAM authentication.
          type: string
          enum:
            - sha256
            - sha512
      additionalProperties: false
      required:
        - type
        - algorithm
    VirtualClusterAuthenticationOauthBearer:
      description: Oauth Bearer authentication scheme for the virtual cluster.
      type: object
      properties:
        type:
          type: string
          enum:
            - oauth_bearer
          x-terraform-transform-const: true
        mediation:
          description: >
            Methods to mediate authentication:

            * passthrough - pass authentication from the client through proxy to
            the backend cluster without any kind of
              validation
            * validate_forward - pass authentication from the client through
            proxy to the backend cluster.
              Proxy does the validation before forwarding it to the client.
            * terminate - terminate authentication at the proxy level and
            originate authentication to the backend cluster
              using the configuration defined at BackendCluster's authentication.
              SASL auth is not originated if authentication on the backend_cluster is not configured.
          type: string
          enum:
            - passthrough
            - validate_forward
            - terminate
        claims_mapping:
          $ref: "#/components/schemas/VirtualClusterAuthenticationClaimsMapping"
        jwks:
          $ref: "#/components/schemas/VirtualClusterAuthenticationJWKS"
        validate:
          $ref: "#/components/schemas/VirtualClusterAuthenticationValidate"
      additionalProperties: false
      required:
        - type
        - mediation
    VirtualClusterAuthenticationClientCertificate:
      description: |-
        Client certificate (mTLS) authentication scheme for the virtual cluster.

        **Requires a minimum runtime version of `1.1`**.
      type: object
      properties:
        type:
          type: string
          enum:
            - client_certificate
          x-terraform-transform-const: true
      example:
        type: client_certificate
      additionalProperties: false
      required:
        - type
      x-min-runtime-version: "1.1"
    VirtualClusterNamespaceTopicSelector:
      type: object
      discriminator:
        propertyName: type
        mapping:
          glob: "#/components/schemas/VirtualClusterNamespaceTopicSelectorGlob"
          exact_list: "#/components/schemas/VirtualClusterNamespaceTopicSelectorExactList"
      oneOf:
        - $ref: "#/components/schemas/VirtualClusterNamespaceTopicSelectorGlob"
        - $ref: "#/components/schemas/VirtualClusterNamespaceTopicSelectorExactList"
      required:
        - type
    VirtualClusterNamespaceIdSelector:
      type: object
      discriminator:
        propertyName: type
        mapping:
          glob: "#/components/schemas/VirtualClusterNamespaceIdSelectorGlob"
          exact_list: "#/components/schemas/VirtualClusterNamespaceIdSelectorExactList"
      oneOf:
        - $ref: "#/components/schemas/VirtualClusterNamespaceIdSelectorGlob"
        - $ref: "#/components/schemas/VirtualClusterNamespaceIdSelectorExactList"
      required:
        - type
    VirtualClusterAuthenticationPrincipalSensitiveDataAware:
      description: A principal for authentication.
      type: object
      properties:
        username:
          $ref: "#/components/schemas/GatewaySecretReferenceOrLiteral"
        password:
          $ref: "#/components/schemas/GatewaySecret"
      required:
        - username
    VirtualClusterAuthenticationClaimsMapping:
      description: Maps JWT claims in the case when sub and scope are presented as
        different claims in your JWT token.
      type: object
      properties:
        sub:
          description: Maps the subject claim.
          type: string
          minLength: 1
        scope:
          description: Maps the scope claim.
          type: string
          minLength: 1
    VirtualClusterAuthenticationJWKS:
      description: JSON Web Key Set configuration for verifying token signatures.
      type: object
      properties:
        endpoint:
          description: URL for JWKS endpoint.
          type: string
          format: uri
          minLength: 1
        timeout:
          description: Total time from establishing connection to receive a response from
            JWKS endpoint.
          type: string
          default: 10s
        cache_expiration:
          description: Duration after which the gateway will fetch and cache JWKS.
          type: string
          default: 1h
      required:
        - endpoint
    VirtualClusterAuthenticationValidate:
      description: Validation rules.
      type: object
      properties:
        audiences:
          description: List of expected audience values. One of them has to match the
            audience claim in the token.
          type: array
          items:
            $ref: "#/components/schemas/VirtualClusterAuthenticationAudience"
          minItems: 1
        issuer:
          description: Expected token issuer in the token.
          type: string
          minLength: 1
    VirtualClusterNamespaceTopicSelectorGlob:
      type: object
      properties:
        type:
          type: string
          enum:
            - glob
          x-terraform-transform-const: true
        glob:
          description: Expose any backend topic that matches this glob pattern (e.g.,
            `operations_data_*`).
          type: string
          format: glob
          minLength: 1
          pattern: ^[A-Za-z0-9._?*-]+$
        conflict:
          description: >
            How to inform the user about conflicts where multiple backend topics
            would map to the same virtual topic name.

            * warn - log in the Event Gateway logs. Additionally, it sets
            knep_namespace_topic_conflict to 1.

            * ignore - do not do anything. It does not cause
            knep_namespace_topic_conflict metric to be set to 1.
          type: string
          default: warn
          enum:
            - warn
            - ignore
      required:
        - type
        - glob
    VirtualClusterNamespaceTopicSelectorExactList:
      type: object
      properties:
        type:
          type: string
          enum:
            - exact_list
          x-terraform-transform-const: true
        exact_list:
          description: Explicit allow-list of backend topic names.
          type: array
          items:
            $ref: "#/components/schemas/NamespaceExactAllowListItem"
          minItems: 1
        conflict:
          description: >
            How to inform the user about conflicts where multiple backend topics
            would map to the same virtual topic name.

            * warn - log in the Event Gateway logs. Additionally, it sets
            knep_namespace_topic_conflict to 1.

            * ignore - do not do anything. It does not cause
            knep_namespace_topic_conflict metric to be set to 1.
          type: string
          default: warn
          enum:
            - warn
            - ignore
      required:
        - type
    VirtualClusterNamespaceIdSelectorGlob:
      type: object
      properties:
        type:
          type: string
          enum:
            - glob
          x-terraform-transform-const: true
        glob:
          description: Expose any id that matches this glob pattern (e.g., `my_id_*`).
          type: string
          format: glob
          minLength: 1
          pattern: ^[A-Za-z0-9._?*-]+$
      required:
        - type
        - glob
    VirtualClusterNamespaceIdSelectorExactList:
      type: object
      properties:
        type:
          type: string
          enum:
            - exact_list
          x-terraform-transform-const: true
        exact_list:
          type: array
          items:
            type: object
            required:
              - value
            properties:
              value:
                type: string
                minLength: 1
          minItems: 1
      required:
        - type
    GatewaySecretReferenceOrLiteral:
      description: >
        A literal value or a reference to an existing secret as a template
        string expression.

        The value is stored and returned by the API as-is, not treated as
        sensitive information.
      type: string
      minLength: 1
      x-examples:
        reference:
          summary: Reference to a secret
          value: ${vault.env['MY_ENV_VAR']}
        literal:
          summary: Literal value
          value: my-literal-value
      x-expression:
        type: string
        fields:
          - vault
    GatewaySecret:
      description: >
        A sensitive value containing the secret or a reference to a secret as a
        template string expression.

        If the value is provided as plain text, it is encrypted at rest and
        omitted from API responses.

        If provided as an expression, the expression itself is stored and
        returned by the API.
      type: string
      example: ${vault.env['MY_ENV_VAR']}
      minLength: 1
      x-expression:
        type: string
        fields:
          - vault
      x-sensitive: true
    VirtualClusterAuthenticationAudience:
      type: object
      properties:
        name:
          type: string
          minLength: 1
      required:
        - name
    NamespaceExactAllowListItem:
      type: object
      properties:
        backend:
          type: string
          minLength: 1
      required:
        - backend
  responses:
    ListVirtualClustersResponse:
      description: A paginated list response for a collection of virtual clusters.
      content:
        application/json:
          schema:
            type: object
            properties:
              meta:
                $ref: "#/components/schemas/CursorMeta"
              data:
                type: array
                items:
                  $ref: "#/components/schemas/VirtualCluster"
    Unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/UnauthorizedError"
          examples:
            UnauthorizedExample:
              $ref: "#/components/examples/UnauthorizedExample"
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ForbiddenError"
          examples:
            UnauthorizedExample:
              $ref: "#/components/examples/ForbiddenExample"
  examples:
    UnauthorizedExample:
      value:
        status: 401
        title: Unauthorized
        instance: kong:trace:8347343766220159418
        detail: Unauthorized
    ForbiddenExample:
      value:
        status: 403
        title: Forbidden
        instance: kong:trace:2723154947768991354
        detail: You do not have permission to perform this action
  securitySchemes:
    personalAccessToken:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: >
        The personal access token is meant to be used as an alternative to
        basic-auth when accessing Konnect via APIs.

        You can generate a Personal Access Token (PAT) from the [personal access
        token page](https://cloud.konghq.com/global/account/tokens/) in the
        Konnect dashboard.

        The PAT token must be passed in the header of a request, for example:

        `curl -X GET 'https://global.api.konghq.com/v2/users/' --header
        'Authorization: Bearer kpat_xgfT...'`
    systemAccountAccessToken:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: >
        The system account access token is meant for automations and
        integrations that are not directly associated with a human identity.

        You can generate a system account Access Token by creating a system
        account and then obtaining a system account access token for that
        account.

        The access token must be passed in the header of a request, for example:

        `curl -X GET 'https://global.api.konghq.com/v2/users/' --header
        'Authorization: Bearer spat_i2Ej...'`
```
