List build sessions

The sessions the caller sees: every one for an engineer, archived included; otherwise their own and the Self Healer’s, with archived ones hidden. Pass `ticketId` for one ticket’s sessions whoever started them — that is what the ticket itself shows — or `status` to narrow. Each row carries its `progress` (the phrase the console shows and whether the next move is a person’s), its pull requests with their state and checks health, and the branch’s preview `deployment` with `elapsedMs` counting up while it builds. `deployment.apps` has each app’s (platform and portals) latest real deployment, and `deployment.failure` names the failed app with its deployment id, URLs, and Vercel’s `errorCode` and `errorMessage` — builds Vercel skipped on purpose (ignored build step, not affected) are never reported. `autoFix` says whether a failing build or check nudges the agent to fix its branch. `search` matches the title, the brief and the branch name.

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

Query Parameters

Name	Type	Required	Description
`limit`	number	Optional	Maximum number of items to return (1-100).Default: `20`
`offset`	number	Optional	Number of items to skip before starting to collect the result set.Default: `0`
`sortBy`	string	Optional	Field to sort by. Allowed values vary by endpoint.Default: `createdAt`
`sortOrder`	string asc desc	Optional	Sort direction.Default: `desc`
`search`	string	Optional	Free-text search across the resource’s primary fields.
`createdAfter`	string	Optional	ISO 8601 timestamp — only return items created after this time.
`createdBefore`	string	Optional	ISO 8601 timestamp — only return items created before this time.
`updatedAfter`	string	Optional	ISO 8601 timestamp — only return items updated after this time.
`ticketId`	string	Optional	Only the sessions started from this ticket, whoever started them.
`status`	string PLANNING PLANNED CODING DRAFT COMPLETED ARCHIVED	Optional	Only sessions in this status.

GETExample request

curl

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

200Example response

json

{
  "message": "Build sessions retrieved successfully!",
  "content": {
    "buildSessions": [
      {
        "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
      }
    ],
    "pagination": {
      "total": 42,
      "limit": 20,
      "offset": 0,
      "hasMore": true
    }
  }
}

In the console

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

Builder

/builder