> ## Documentation Index
> Fetch the complete documentation index at: https://bilt.me/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# bilt_get_session

> Get current session info, preview URL, and workflow status for a project

## Overview

Retrieves the current session for a project, including preview URLs and workflow status. Use this before sending messages to check whether a workflow is already queued/running and to get the preview URL for the app.

<Info>
  Pass the `projectId` returned from [bilt\_create\_project](/docs/api-reference/bilt_create_project) or [bilt\_list\_projects](/docs/api-reference/bilt_list_projects).
</Info>

## Parameters

<ParamField path="projectId" type="string" required>
  The project to query

  * **Format**: UUID
  * **Example**: `"660e8400-e29b-41d4-a716-446655440001"`
</ParamField>

## Response

The tool returns JSON with session details and workflow status:

<ResponseField name="session" type="object | null">
  Current session, if one exists. Includes session metadata, sandbox ID, and `previewUrl` for the live app preview. The raw `previews` object is omitted from the MCP response.
</ResponseField>

<ResponseField name="workflows" type="array" required>
  Active workflow item followed by any queued prompt items for the project. Each item uses lowercase status values.

  <Expandable title="Workflow Item">
    <ResponseField name="id" type="string">
      Workflow ID
    </ResponseField>

    <ResponseField name="status" type="string">
      One of `queued`, `started`, `running`, `paused`, `completed`, `error`, `cancelled`, or `none`
    </ResponseField>

    <ResponseField name="startedAt" type="string">
      ISO timestamp when the workflow started, or when a queued prompt was accepted
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO timestamp of the last workflow update
    </ResponseField>

    <ResponseField name="errorMessage" type="string | null">
      Error details when status is `error`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hasActiveWorkflows" type="boolean" required>
  Whether any workflow is currently `queued`, `started`, `running`, or `paused`
</ResponseField>

## Example Usage

<CodeGroup>
  ```json Request theme={null}
  {
    "projectId": "660e8400-e29b-41d4-a716-446655440001"
  }
  ```

  ```json Response theme={null}
  {
    "session": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-02-10T15:00:00.000Z",
      "updatedAt": "2026-02-10T15:05:30.000Z",
      "sandbox": {
        "id": "sandbox-550e8400-e29b-41d4-a716-446655440000"
      },
      "previewUrl": "https://app.bilt.me/project/660e8400-e29b-41d4-a716-446655440001/preview"
    },
    "workflows": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "status": "running",
        "startedAt": "2026-02-10T15:00:00.000Z",
        "updatedAt": "2026-02-10T15:05:30.000Z",
        "errorMessage": null
      },
      {
        "id": "880e8400-e29b-41d4-a716-446655440003",
        "status": "queued",
        "startedAt": "2026-02-10T15:06:00.000Z",
        "updatedAt": "2026-02-10T15:06:00.000Z",
        "errorMessage": null
      }
    ],
    "hasActiveWorkflows": true
  }
  ```
</CodeGroup>

## Common Patterns

### Check Before Sending a Message

```text theme={null}
Agent workflow:
1. User: "Add a login page to my app"
2. Agent calls bilt_get_session({ projectId })
3. If hasActiveWorkflows is true, wait or offer to cancel
4. Agent calls bilt_send_message({ projectId, message: "Add login page" })
```

### Monitor Build Progress

Poll `bilt_get_session` every few seconds until `hasActiveWorkflows` is false. This includes queued work; do not send unrelated follow-up work while a queued item is still present.

## Related Tools

<CardGroup cols={3}>
  <Card title="bilt_send_message" icon="paper-plane" href="/docs/api-reference/bilt_send_message">
    Send workflow instructions
  </Card>

  <Card title="bilt_get_messages" icon="message" href="/docs/api-reference/bilt_get_messages">
    View conversation history
  </Card>

  <Card title="bilt_cancel_workflow" icon="xmark" href="/docs/api-reference/bilt_cancel_workflow">
    Stop running workflow
  </Card>
</CardGroup>