---
title: "List all Upstreams"
url: "https://nov18-dev.movespot.fyi/apis/konnect-runtime-groups-configuration-0/versions/af18902c-58f1-49d7-8ec2-9987b4e0d1bd/operations/list-upstreams"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-runtime-groups-configuration-0/versions/af18902c-58f1-49d7-8ec2-9987b4e0d1bd.md

# List all Upstreams

`GET` `/runtime-groups/{runtimeGroupId}/core-entities/upstreams`

Operation ID: `list-upstreams`

List all registered upstreams. You can filter the results by pagination size, offset, or tags like `/upstreams?size=10&offset=0`.

## Path parameters

- `runtimeGroupId` (string, required) - The ID of your runtime group. This variable is available in the Konnect manager

## Query parameters

- `size` (integer, optional) - Number of resources to be returned.
- `offset` (string, optional) - Offset from which to return the next set of resources. Use the value of the 'offset' field from the response of a list operation as input here to paginate through all the resources
- `tags` (string, optional) - A list of tags to filter the list of resources on. Multiple tags can be concatenated using ',' to mean AND or using '/' to mean OR.

## Responses

- `200` - A successful response listing Upstreams

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Konnect Runtime Groups Configuration
  version: 0.0.1
servers:
  - url: https://us.api.konghq.com/v2
    description: United-States Production region
  - url: https://eu.api.konghq.com/v2
    description: Europe Production region
  - url: https://au.api.konghq.com/v2
    description: Australia Production region
  - url: https://me.api.konghq.com/v2
    description: Middle-East Production region
  - url: https://in.api.konghq.com/v2
    description: India Production region
  - url: https://sg.api.konghq.com/v2
    description: Singapore Production region
paths:
  /runtime-groups/{runtimeGroupId}/core-entities/upstreams:
    parameters:
      - $ref: "#/components/parameters/runtimeGroupId"
    get:
      operationId: list-upstreams
      summary: List all Upstreams
      description: >
        List all registered upstreams. You can filter the results by pagination
        size, offset, or tags like `/upstreams?size=10&offset=0`.
      parameters:
        - $ref: "#/components/parameters/pagination-size"
        - $ref: "#/components/parameters/pagination-offset"
        - $ref: "#/components/parameters/pagination-tags-filter"
      responses:
        "200":
          description: A successful response listing Upstreams
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Upstream"
                  offset:
                    $ref: "#/components/schemas/pagination-offset-response"
              examples:
                example:
                  value:
                    data:
                      - algorithm: round-robin
                        hash_fallback: none
                        hash_on: none
                        hash_on_cookie_path: /
                        healthchecks:
                          active:
                            concurrency: 10
                            healthy:
                              http_statuses:
                                - 200
                                - 302
                              interval: 0
                              successes: 0
                            http_path: /
                            https_verify_certificate: true
                            timeout: 1
                            type: http
                            unhealthy:
                              http_failures: 0
                              http_statuses:
                                - 429
                                - 404
                                - 500
                                - 501
                                - 502
                                - 503
                                - 504
                                - 505
                              interval: 0
                              tcp_failures: 0
                              timeouts: 0
                          passive:
                            healthy:
                              http_statuses:
                                - 200
                                - 201
                                - 202
                                - 203
                                - 204
                                - 205
                                - 206
                                - 207
                                - 208
                                - 226
                                - 300
                                - 301
                                - 302
                                - 303
                                - 304
                                - 305
                                - 306
                                - 307
                                - 308
                              successes: 0
                            type: http
                            unhealthy:
                              http_failures: 0
                              http_statuses:
                                - 429
                                - 500
                                - 503
                              tcp_failures: 0
                              timeouts: 0
                          threshold: 0
                        id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e
                        name: api.example.internal
                        slots: 10000
                    offset: string
      tags:
        - Upstreams
security:
  - konnectAccessToken: []
  - personalAccessToken: []
components:
  parameters:
    runtimeGroupId:
      name: runtimeGroupId
      in: path
      required: true
      schema:
        type: string
        example: 9524ec7d-36d9-465d-a8c5-83a3c9390458
      description: The ID of your runtime group. This variable is available in the
        Konnect manager
    pagination-size:
      description: Number of resources to be returned.
      in: query
      name: size
      schema:
        type: integer
        default: 100
        maximum: 1000
        minimum: 1
    pagination-offset:
      description: Offset from which to return the next set of resources. Use the
        value of the 'offset' field from the response of a list operation as
        input here to paginate through all the resources
      in: query
      name: offset
      schema:
        type: string
    pagination-tags-filter:
      description: A list of tags to filter the list of resources on. Multiple tags
        can be concatenated using ',' to mean AND or using '/' to mean OR.
      example: tag1,tag2
      in: query
      name: tags
      schema:
        type: string
  schemas:
    Upstream:
      description: The upstream object represents a virtual hostname and can be used
        to loadbalance incoming requests over multiple services (targets). So
        for example an upstream named `service.v1.xyz` for a service object
        whose `host` is `service.v1.xyz`. Requests for this service would be
        proxied to the targets defined within the upstream. An upstream also
        includes a [health checker][healthchecks], which is able to enable and
        disable targets based on their ability or inability to serve requests.
        The configuration for the health checker is stored in the upstream
        object, and applies to all of its targets.
      type: object
      properties:
        algorithm:
          description: Which load balancing algorithm to use.
          type: string
          default: round-robin
        client_certificate:
          description: If set, the certificate to be used as client certificate while TLS
            handshaking to the upstream server.
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
        created_at:
          description: Unix epoch when the resource was created.
          type: integer
          example: 1422386534
        updated_at:
          description: Unix epoch when the resouce was updated.
          type: integer
          example: 1422386534
        hash_fallback:
          description: What to use as hashing input if the primary `hash_on` does not
            return a hash (eg. header is missing, or no Consumer identified).
            Not available if `hash_on` is set to `cookie`.
          type: string
          default: none
        hash_fallback_header:
          description: The header name to take the value from as hash input. Only required
            when `hash_fallback` is set to `header`.
          type: string
        hash_fallback_query_arg:
          description: The name of the query string argument to take the value from as
            hash input. Only required when `hash_fallback` is set to
            `query_arg`.
          type: string
        hash_fallback_uri_capture:
          description: The name of the route URI capture to take the value from as hash
            input. Only required when `hash_fallback` is set to `uri_capture`.
          type: string
        hash_on:
          description: What to use as hashing input. Using `none` results in a
            weighted-round-robin scheme with no hashing.
          type: string
          default: none
        hash_on_cookie:
          description: The cookie name to take the value from as hash input. Only required
            when `hash_on` or `hash_fallback` is set to `cookie`. If the
            specified cookie is not in the request, Kong will generate a value
            and set the cookie in the response.
          type: string
        hash_on_cookie_path:
          description: The cookie path to set in the response headers. Only required when
            `hash_on` or `hash_fallback` is set to `cookie`.
          type: string
          default: /
        hash_on_header:
          description: The header name to take the value from as hash input. Only required
            when `hash_on` is set to `header`.
          type: string
        hash_on_query_arg:
          description: The name of the query string argument to take the value from as
            hash input. Only required when `hash_on` is set to `query_arg`.
          type: string
        hash_on_uri_capture:
          description: The name of the route URI capture to take the value from as hash
            input. Only required when `hash_on` is set to `uri_capture`.
          type: string
        healthchecks:
          type: object
          properties:
            active:
              type: object
              properties:
                concurrency:
                  type: integer
                  default: 10
                headers:
                  type: object
                healthy:
                  type: object
                  properties:
                    http_statuses:
                      type: array
                      items:
                        type: integer
                      default:
                        - 200
                        - 302
                    interval:
                      type: number
                      default: 0
                    successes:
                      type: integer
                      default: 0
                http_path:
                  type: string
                  default: /
                https_sni:
                  type: string
                https_verify_certificate:
                  type: boolean
                  default: true
                timeout:
                  type: number
                  default: 1
                type:
                  type: string
                  default: http
                unhealthy:
                  type: object
                  properties:
                    http_failures:
                      type: integer
                      default: 0
                    http_statuses:
                      type: array
                      items:
                        type: integer
                      default:
                        - 429
                        - 404
                        - 500
                        - 501
                        - 502
                        - 503
                        - 504
                        - 505
                    interval:
                      type: number
                      default: 0
                    tcp_failures:
                      type: integer
                      default: 0
                    timeouts:
                      type: integer
                      default: 0
            passive:
              type: object
              properties:
                healthy:
                  type: object
                  properties:
                    http_statuses:
                      type: array
                      items:
                        type: integer
                      default:
                        - 200
                        - 201
                        - 202
                        - 203
                        - 204
                        - 205
                        - 206
                        - 207
                        - 208
                        - 226
                        - 300
                        - 301
                        - 302
                        - 303
                        - 304
                        - 305
                        - 306
                        - 307
                        - 308
                    successes:
                      type: integer
                      default: 0
                type:
                  type: string
                  default: http
                unhealthy:
                  type: object
                  properties:
                    http_failures:
                      type: integer
                      default: 0
                    http_statuses:
                      type: array
                      items:
                        type: integer
                      default:
                        - 429
                        - 500
                        - 503
                    tcp_failures:
                      type: integer
                      default: 0
                    timeouts:
                      type: integer
                      default: 0
            threshold:
              type: number
              default: 0
        host_header:
          description: The hostname to be used as `Host` header when proxying requests
            through Kong.
          type: string
        id:
          type: string
        name:
          description: This is a hostname, which must be equal to the `host` of a service.
          type: string
        slots:
          description: The number of slots in the load balancer algorithm. If `algorithm`
            is set to `round-robin`, this setting determines the maximum number
            of slots. If `algorithm` is set to `consistent-hashing`, this
            setting determines the actual number of slots in the algorithm.
            Accepts an integer in the range `10`-`65536`.
          type: integer
          default: 10000
        tags:
          description: An optional set of strings associated with the Upstream for
            grouping and filtering.
          type: array
          items:
            type: string
        use_srv_name:
          description: If set, the balancer will use SRV hostname(if DNS Answer has SRV
            record) as the proxy upstream `Host`.
          type: boolean
          default: false
      example:
        algorithm: round-robin
        hash_fallback: none
        hash_on: none
        hash_on_cookie_path: /
        healthchecks:
          active:
            concurrency: 10
            healthy:
              http_statuses:
                - 200
                - 302
              interval: 0
              successes: 0
            http_path: /
            https_verify_certificate: true
            timeout: 1
            type: http
            unhealthy:
              http_failures: 0
              http_statuses:
                - 429
                - 404
                - 500
                - 501
                - 502
                - 503
                - 504
                - 505
              interval: 0
              tcp_failures: 0
              timeouts: 0
          passive:
            healthy:
              http_statuses:
                - 200
                - 201
                - 202
                - 203
                - 204
                - 205
                - 206
                - 207
                - 208
                - 226
                - 300
                - 301
                - 302
                - 303
                - 304
                - 305
                - 306
                - 307
                - 308
              successes: 0
            type: http
            unhealthy:
              http_failures: 0
              http_statuses:
                - 429
                - 500
                - 503
              tcp_failures: 0
              timeouts: 0
          threshold: 0
        id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e
        name: api.example.internal
        slots: 10000
    pagination-offset-response:
      description: Offset is used to paginate through the API. Provide this value to
        the next list operation to fetch the next page
      type: string
  securitySchemes:
    konnectAccessToken:
      type: http
      scheme: bearer
      description: >-
        The Konnect access token is meant to be used by the Konnect dashboard
        and the decK CLI to

        authenticate with.
    personalAccessToken:
      type: http
      scheme: bearer
      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 in the Konnect
        dashboard.
```
