Skip to content

Get a listener

GET
https://lb-api.ezghcloud.com/v1/organizations/{orgId}/projects/{projectId}/load-balancers/{loadBalancer}/listeners/{listener}

Authorization

  • apiKeyoptionalHTTP
  • oauthoptionalHTTP
  • sessionCookieoptionalAPI key in cookie

Path parameters

  • orgIdstringrequired

    UUID or prefixed ID (org_…)

  • projectIdstringrequired

    UUID or prefixed ID (prj_…)

  • loadBalancerstringrequired
  • listenerstringrequired

Returns

200

The listener.

JSON
  • additionalCertificatesarray ofstringrequired

    SNI certificates beyond the default, at most 24: a client whose SNI one of them covers gets it, and any other client the default certificate. Each renews on its own. Empty on tcp and http.

  • allowedSourceCidrsarray ofstringrequired

    CIDRs allowed to connect: IPv4, and IPv6 where IPv6 is available. Each family admits only the clients its own ranges cover: a list with no IPv6 range admits no IPv6 client. Defaults to everyone: ["0.0.0.0/0"], with "::/0" where IPv6 is available.

  • certificatestring | nullrequired
  • createdAtstringrequired
    format: date-time
  • defaultActionActionornullrequired

    An http or https listener's action for a request no rule matches. Null on tcp and tls.

    2 variants

    One of the following:

  • idstringrequired
  • idleTimeoutSecondsintegerrequired
  • loadBalancerstringrequired
  • portintegerrequired
  • protocoltcportlsorhttporhttpsrequired
  • rulesarray ofobjectrequired

    Ordered: the first rule that matches a request acts on it, and the default action takes the rest. At most 100. Sent, it replaces the whole list. Empty on tcp and tls.

    3 properties
    • actionobjectrequired

      type names the one of forward, redirect and fixedResponse that is set; the others are null.

      4 properties
      • fixedResponseFixedResponseornullrequired
        2 variants

        One of the following:

        • 3 properties
          • bodystringrequired

            UTF-8, at most 1024 bytes. Default empty.

          • contentTypetext/plainortext/htmlorapplication/jsonrequired

            Default text/plain.

          • statusCodeintegerrequired
            maximum: 599, minimum: 200
        • null
      • forwardForwardornullrequired
        2 variants

        One of the following:

        • Forward
          3 properties
          • requestHeaderModifierHeaderModifierornullrequired

            Changes the request's headers before it goes to the target.

            2 variants

            One of the following:

          • responseHeaderModifierHeaderModifierornullrequired

            Changes the target's response headers before they reach the client.

            2 variants

            One of the following:

          • targetGroupsarray ofobjectrequired

            Each request picks a group by weight; the sum of weights is above 0.

            2 properties
            • targetGroupstringrequired

              An http target group of the listener's load balancer.

            • weightintegerrequired

              Required with more than one group; 0 never receives.

              maximum: 999, minimum: 0
        • null
      • redirectRedirectornullrequired
        2 variants

        One of the following:

        • Redirect
          5 properties
          • hoststring | nullrequired
            maxLength: 253
          • pathstring | nullrequired
            maxLength: 1024
          • portinteger | nullrequired
            maximum: 65535, minimum: 1
          • schemehttporhttpsornullrequired
          • statusCode301or302or307or308required

            Default 302.

        • null
      • typeforwardorredirectorfixedResponserequired
    • matchobjectrequired

      Fields AND together. Entries OR within hosts, paths and methods, and AND within headers and queryParams. An empty field matches anything.

      5 properties
      • headersarray ofobjectrequired
        2 properties
        • namestringrequired

          An HTTP token; header names match case-insensitively.

          maxLength: 128
        • valuestringrequired

          Printable ASCII, matched exactly.

          maxLength: 256, minLength: 1
      • hostsarray ofstringrequired

        Exact names, or *.example.com for any name ending in .example.com. Lowercase; the port is ignored.

        maxLength: 253
      • methodsarray ofstringrequired

        Uppercase.

        maxLength: 32
      • pathsarray ofobjectrequired
        2 properties
        • typeexactorprefixrequired

          prefix matches on segment boundaries: /api matches /api and /api/x, not /apix.

        • valuestringrequired

          Starts with /; printable ASCII without space, # or ?.

          maxLength: 1024, minLength: 1
      • queryParamsarray ofobjectrequired
        2 properties
        • namestringrequired

          An HTTP token; header names match case-insensitively.

          maxLength: 128
        • valuestringrequired

          Printable ASCII, matched exactly.

          maxLength: 256, minLength: 1
    • namestring | nullrequired
      maxLength: 64
  • targetGroupstring | nullrequired

    A tcp or tls listener's target group, and an http or https listener's when its default action forwards to exactly one; else null.

  • updatedAtstringrequired
    format: date-time

400

invalid_request (with issues), invalid_cursor, or the endpoint's own 400 codes.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

401

unauthenticated: no credential, or one that doesn't check out.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

403

access_denied: the caller's policies don't allow the action; forbidden_origin: a cookie-authenticated write from an origin that isn't allowed; spend_limit_reached.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

404

not_found: unknown, malformed, or in an organization the caller isn't in.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

429

too_many_requests, with Retry-After; or quota_exceeded (a rate, usage or concurrency quota, with quota), never with Retry-After.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

500

internal_error: a bug; the details are in the logs, under the request ID.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

503

unavailable: a dependency the request needs is down. Retry after Retry-After.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close