---
title: "Agent modes of a session: the mode of recent turns, its plans, the free Chat messages left today, the prices of Plan and Chat, the picked look, whether \"About my business\" is filled, and what the builder can look at here (pictures, web pages, Figma, documents)"
method: GET
path: "/builder/sessions/{sessionId}/modes"
tags: ["Builder"]
---

# Agent modes of a session: the mode of recent turns, its plans, the free Chat messages left today, the prices of Plan and Chat, the picked look, whether "About my business" is filled, and what the builder can look at here (pictures, web pages, Figma, documents)

`GET /builder/sessions/{sessionId}/modes`

## Request

- Base URL: `https://hostingsurge.com/api/v1`
- URL: `https://hostingsurge.com/api/v1/builder/sessions/{sessionId}/modes`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Host-hs_session`

## Path parameters

- `sessionId` string, uuid, required

## Response `200`

The modes state

- object
  - `turns` object[], required: The mode of each recent turn (turns sent before agent modes are Build)
    - `turnId` string, uuid, required
    - `mode` 'build' | 'plan' | 'chat', required
    - `task` string, nullable, required
    - `effort` string, nullable, required
    - `planId` string, uuid, nullable, required
    - `refusedEdits` integer, required
    - `shown` object[], required: What the message showed the builder, in its order
      - `kind` 'image' | 'page' | 'figma' | 'document' | 'mention', required
      - `referenceId` string, uuid, nullable, required: The stored reference (its picture: GET …/references/{id}/image while it is kept)
      - `label` string, required
  - `plans` object[], required: The session's plans, newest first
    - `id` string, uuid, required
    - `sessionId` string, uuid, required
    - `turnId` string, uuid, required: The Plan turn that wrote it
    - `status` 'draft' | 'building' | 'done' | 'dismissed', required
    - `plan` object, required
      - `title` string, required
      - `goal` string, required
      - `summary` string, required
      - `pages` object[], required
        - `name` string, required
        - `path` string, nullable, required
        - `sections` string[], required
      - `steps` object[], required
        - `id` string, required
        - `title` string, required
        - `detail` string, required
        - `size` 'small' | 'medium' | 'large', required
        - `credits` number, required
        - `include` boolean, required
        - `done` boolean, required
        - `turnId` string, nullable, required
      - `questions` string[], required
    - `credits` number, required: Estimated Build Credits of the ticked steps not built yet
    - `createdAt` string, required: ISO-8601 timestamp
    - `updatedAt` string, required: ISO-8601 timestamp
  - `chat` object, required
    - `freePerDay` integer, required
    - `freeLeft` integer, required
    - `credits` number, required: Price of a Chat message after the free ones
  - `plan` object, required
    - `credits` number, required: Price of a Plan message
  - `look` object, nullable, required
    - `name` string, required
    - `seed` object, required
      - `background` string, required: The page background
      - `primary` string, required: The brand color: buttons, links, accents
      - `accent` string, required: A second color for highlights and badges
      - `dark` boolean, required: A dark site (light text on a dark page)
      - `pairing` 'modern' | 'editorial' | 'elegant' | 'friendly' | 'bold' | 'classic' | 'reading' | 'expressive' | 'playful' | 'technical' | 'geometric' | 'sturdy', required
      - `hero` 'centered' | 'split' | 'full-bleed', required
      - `radius` 'sharp' | 'soft' | 'round', required
    - `applied` boolean, required
  - `knowledge` object, required
    - `filled` boolean, required
  - `capabilities` object, required
    - `pictures` boolean, required: Pictures can be shown to the builder (vision)
    - `pages` boolean, required: A web page can be captured (the screenshot worker is on); otherwise ask for a screenshot
    - `figma` 'off' | 'connect' | 'ready', required: off: not set up on this server; connect: the member must connect Figma; ready
    - `documents` boolean, required

## Other responses

- `400`: Invalid request (code invalid_request; details.reason: unsupported, too_large, unreadable, no_text, reference_gone)
- `401`: Missing or invalid session/token (code unauthorized)
- `403`: Authenticated but not permitted (code forbidden; details.reason private_beta or role)
- `404`: Not found or not visible to the caller (code not_found)
- `409`: Refused for now (code conflict; details.reason: plan_building, plan_dismissed, plan_empty, refines_used, figma_connect, archived, stale)
- `429`: Too many requests (code rate_limited; details.reason mode_rate, daily_budget, provider_busy); see Retry-After
- `501`: Not available on this server (code not_configured; details.reason capture_off, figma_off, migration_pending)

---

[API](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api.md) · [All operations](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/revisions/4d08337cdff1?raw)