bilt_get_session

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.

Pass the projectId returned from bilt_create_project or bilt_list_projects.

Parameters

string

required

The project to query

Format: UUID
Example: "660e8400-e29b-41d4-a716-446655440001"

Response

The tool returns JSON with session details and workflow status:

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.

array

required

Active workflow item followed by any queued prompt items for the project. Each item uses lowercase status values.

Show Workflow Item

string

Workflow ID

string

One of queued, started, running, paused, completed, error, cancelled, or none

string

ISO timestamp when the workflow started, or when a queued prompt was accepted

string

ISO timestamp of the last workflow update

string | null

Error details when status is error

boolean

required

Whether any workflow is currently queued, started, running, or paused

Example Usage

{
  "projectId": "660e8400-e29b-41d4-a716-446655440001"
}

{
  "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
}

Common Patterns

Check Before Sending a Message

Agent workflow:
User: "Add a login page to my app"
Agent calls bilt_get_session({ projectId })
If hasActiveWorkflows is true, wait or offer to cancel
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.

bilt_send_message

Send workflow instructions

bilt_get_messages

View conversation history

bilt_cancel_workflow

Stop running workflow

Get Started

Client Setup

Tools Reference

bilt_get_session

Overview

Parameters

Response

Example Usage

Common Patterns

Check Before Sending a Message

Monitor Build Progress

bilt_send_message

bilt_get_messages

bilt_cancel_workflow

​Overview

​Parameters

​Response

​Example Usage

​Common Patterns

​Check Before Sending a Message

​Monitor Build Progress

​Related Tools

bilt_send_message

bilt_get_messages

bilt_cancel_workflow

Overview

Parameters

Response

Example Usage

Common Patterns

Check Before Sending a Message

Monitor Build Progress

Related Tools