Get a build session

One session in full: what it is doing (`progress`), its pull requests and the preview build of its branch, its spend (`usage`, with `contextTokens` saying how full the agent’s window is), the ticket it came from, the error it was opened to fix if the Self Healer opened it, and what the caller may do with it (`viewer`). Reading it keeps the GitHub and Vercel mirrors current on the console’s own throttle. The transcript is not here — it is a page at a time under `/messages`.

Required scope

The access token must carry this scope. A token missing it gets 403 Forbidden. Grant them to an API client under Dev Tools → API, to an assistant or CLI sign-in when you approve or edit it under Dev Tools, and to a teammate under Employee → Permissions.

builder:read

Path Parameters

Name	Type	Required	Description
`sessionId`	string	Required	Build session ID.

GETExample request

curl

curl -X GET "https://www.pxb.app/api/public/v1/build-sessions/{sessionId}" \
  -H "Authorization: Bearer your_access_token"

200Example response

json

{
  "message": "Build session retrieved successfully!",
  "content": {
    "buildSession": {
      "id": "bse_a1b2c3",
      "title": "Expose builder session status over MCP",
      "description": "Add build-session tools to the MCP server: list, status, messages, and the write actions, gated on the builder scopes.",
      "status": "DRAFT",
      "progress": {
        "status": "DRAFT",
        "label": "Draft",
        "phrase": "Built — pull request open · preview building",
        "agentBusy": false,
        "awaitingReply": true,
        "awaitingAnswers": false,
        "interrupted": false,
        "terminal": false
      },
      "bot": false,
      "planMode": false,
      "autoMode": false,
      "autoFix": false,
      "plan": null,
      "planApprovedAt": null,
      "model": "claude-sonnet-5-5",
      "agentStarted": true,
      "branchName": "builder/eng-214-session-status-over-mcp",
      "pullRequests": [
        {
          "id": "bpr_7c1d",
          "number": 548,
          "url": "https://github.com/pixelbase-inc/web/pull/548",
          "branchName": "builder/eng-214-session-status-over-mcp",
          "baseBranch": "master",
          "title": "feat(mcp): builder sessions and their status as tools",
          "stage": "STANDARD",
          "ordinal": 1,
          "state": "OPEN",
          "health": "CHECKS_RUNNING",
          "healthLabel": "Checks running",
          "open": true,
          "additions": 412,
          "deletions": 38,
          "changedFiles": 14
        }
      ],
      "deployment": {
        "state": "BUILDING",
        "label": "Building…",
        "building": true,
        "ready": false,
        "url": "https://platform-git-builder-eng-214-session-status-over-mcp.pxb.dev",
        "inspectorUrl": "https://vercel.com/pixelbase/platform/4Q7m2k1p",
        "startedAt": "2026-10-09T15:31:02.000Z",
        "elapsedMs": 184000,
        "updatedAt": "2026-10-09T15:34:06.000Z",
        "apps": [
          {
            "app": "platform",
            "deploymentId": "dpl_4Q7m2k1p",
            "state": "BUILDING",
            "url": "https://platform-git-builder-eng-214-session-status-over-mcp.pxb.dev",
            "inspectorUrl": "https://vercel.com/pixelbase/platform/4Q7m2k1p",
            "errorCode": null,
            "errorMessage": null,
            "startedAt": "2026-10-09T15:31:02.000Z",
            "commitSha": "9b2f6c1"
          }
        ],
        "failure": null
      },
      "previewHref": "https://platform-git-builder-eng-214-session-status-over-mcp.pxb.dev/dashboard?pass=…",
      "ticket": {
        "id": "tkt_214",
        "key": "ENG-214",
        "title": "Builder over MCP",
        "status": "IN_PROGRESS",
        "projectName": "Engineering"
      },
      "createdBy": {
        "id": "emp_12ab",
        "referenceId": "PXB-0042",
        "bot": false,
        "status": "ACTIVE",
        "jobTitleId": null,
        "departmentId": null,
        "managerId": null,
        "user": {
          "id": "usr_9f1e",
          "fullname": "Sam Okafor",
          "email": "sam@pxb.app",
          "profileImgPath": null
        }
      },
      "createdById": "emp_12ab",
      "viewer": {
        "canPrompt": true,
        "isOwner": true,
        "canOpenPage": true,
        "canAdminister": false,
        "canUseAutoMode": false
      },
      "createdAt": "2026-10-09T14:02:00.000Z",
      "updatedAt": "2026-10-09T15:34:06.000Z",
      "closedAt": null,
      "usage": {
        "tokensBurnt": 1842300,
        "inputTokens": 1610000,
        "outputTokens": 48300,
        "cacheCreationInputTokens": 92000,
        "cacheReadInputTokens": 2410000,
        "events": 61,
        "contextTokens": 212000
      },
      "healedError": null
    }
  }
}

In the console

The same thing done by hand, for anyone comparing the API against the screen they already use.

Builder

/builder

Open a session.