# describeHostedQuickstartConnection

`GET /apis/cra.diagrid.io/v1beta1/projects/{ProjectId}/hosted-quickstarts/{HostedQuickstartId}/connection`

How to reach this session's runner directly, for the live event stream.
The stream is deliberately not proxied through the control plane: the client connects to the runner through the regional gateway with the token in this descriptor. Reissue by calling this again — the token is short-lived.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ProjectId` | string | Yes | Unique identifier of the project. |
| `HostedQuickstartId` | string | Yes | Name of the hosted quickstart. |

## Responses

### 200 — The connection descriptor.

`application/json`

How to reach the session's runner directly. The live event stream is NOT proxied through the control plane: the browser connects to the runner through the regional gateway using this descriptor. A control-plane hop could not carry it anyway, because the API client buffers responses.

- `gatewayHost` (string) — Required. The regional gateway host serving this session's project.
- `scheme` (string) — Required.
- `appId` (string) — Required. The runner's App ID, invoked through the gateway.
- `apiToken` (string (password)) — Required. Project-scoped token for the gateway call. Short-lived and scoped to this session's runner.
- `endpointTemplate` (string) — Required. Template for the runner's own paths, into which the client substitutes the method it wants.

### 403 — Not the session's owner.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### 404 — No such session.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### 409 — There is no runner to connect to and polling cannot change that — `session_suspended`, `session_failed` or `session_deleting`.

`application/json`

Why the connection descriptor cannot be issued for a session the caller is entitled to. It carries no descriptor fields at all: a "not ready" answer must never let a client read a gateway host or token off it. A retryable condition answers 503 with `Retry-After`; a terminal one answers 409 with none. The reason travels in this body and in the error-reason header, because the status code alone cannot say which condition it was.

- `error` (string) — Required. A sentence for a human.
- `reason` (string) — Required. The machine code to branch on. Retryable, answered with 503: `session_provisioning` — the controller is still building the runner. `runner_not_provisioned` — the session has no runner App ID or routing token yet. `gateway_not_ready` — the project's region has no HTTP gateway endpoint yet. Terminal, answered with 409: `session_suspended` — the runner is scaled to zero; resume it first. `session_failed` — provisioning failed; the session can only be deleted. `session_deleting` — the session is terminating. One of: `session_provisioning`, `runner_not_provisioned`, `gateway_not_ready`, `session_suspended`, `session_failed`, `session_deleting`.
- `state` (string) — The session's state when the descriptor was refused. One of: `Provisioning`, `Active`, `Suspended`, `Failed`, `Deleting`.

### 503 — The runner is not up yet — `session_provisioning`, `runner_not_provisioned` or `gateway_not_ready`. Carries `Retry-After`.

`application/json`

Why the connection descriptor cannot be issued for a session the caller is entitled to. It carries no descriptor fields at all: a "not ready" answer must never let a client read a gateway host or token off it. A retryable condition answers 503 with `Retry-After`; a terminal one answers 409 with none. The reason travels in this body and in the error-reason header, because the status code alone cannot say which condition it was.

- `error` (string) — Required. A sentence for a human.
- `reason` (string) — Required. The machine code to branch on. Retryable, answered with 503: `session_provisioning` — the controller is still building the runner. `runner_not_provisioned` — the session has no runner App ID or routing token yet. `gateway_not_ready` — the project's region has no HTTP gateway endpoint yet. Terminal, answered with 409: `session_suspended` — the runner is scaled to zero; resume it first. `session_failed` — provisioning failed; the session can only be deleted. `session_deleting` — the session is terminating. One of: `session_provisioning`, `runner_not_provisioned`, `gateway_not_ready`, `session_suspended`, `session_failed`, `session_deleting`.
- `state` (string) — The session's state when the descriptor was refused. One of: `Provisioning`, `Active`, `Suspended`, `Failed`, `Deleting`.

### default — Unexpected error.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.