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

# Get Session

> Returns a single agent session by its id.



## OpenAPI

````yaml api-reference/openapi/sessions.json GET /api/sessions/{sessionId}
openapi: 3.1.0
info:
  title: Recoup API - Sessions
  description: >-
    Sessions — sandboxed runs of an LLM-driven agent with tool use, lifecycle
    hooks, and persistence. Each session pairs one Vercel Sandbox with one or
    more chat threads.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.recoupable.dev
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /api/sessions/{sessionId}:
    get:
      summary: Get session by id
      description: Returns a single agent session by its id.
      parameters:
        - name: sessionId
          in: path
          required: true
          description: The id of the session to fetch.
          schema:
            type: string
      responses:
        '200':
          description: Session retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSessionResponse'
        '401':
          description: Unauthorized - invalid or missing API key / Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - the authenticated account does not own this session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found - no session exists with the given id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    GetSessionResponse:
      type: object
      required:
        - session
      properties:
        session:
          $ref: '#/components/schemas/Session'
    Error:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
          enum:
            - error
          description: Always `"error"` for error responses.
        error:
          type: string
          description: Human-readable error message.
    Session:
      type: object
      description: >-
        Agent session returned by [`POST
        /api/sessions`](/api-reference/sessions/create), [`GET
        /api/sessions/{sessionId}`](/api-reference/sessions/get), and [`PATCH
        /api/sessions/{sessionId}`](/api-reference/sessions/patch). The api
        serializes every field listed in `required` on each response, including
        `isNewBranch` (boolean, from the non-null `sessions.is_new_branch`
        column) and `artistId` (UUID or null).
      required:
        - id
        - userId
        - artistId
        - title
        - status
        - isNewBranch
        - globalSkillRefs
        - lifecycleVersion
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: Session id (nanoid).
        userId:
          type: string
          format: uuid
          description: >-
            Owning account id. Named `userId` here for compatibility with
            existing clients; on the server side this is the account_id foreign
            key into the accounts table.
        title:
          type: string
        status:
          type: string
          enum:
            - running
            - completed
            - failed
            - archived
        repoOwner:
          type: string
          nullable: true
          description: GitHub repo owner if the session is bound to a repository.
        repoName:
          type: string
          nullable: true
        branch:
          type: string
          nullable: true
        cloneUrl:
          type: string
          nullable: true
          description: Clone URL the sandbox should fetch from.
        isNewBranch:
          type: boolean
          description: >-
            Always present on session responses. True when this session created
            and pushed a new branch (not committing back to the original); false
            otherwise.
        globalSkillRefs:
          type: array
          description: Skills attached to the agent at provision time.
          items:
            type: object
            additionalProperties: true
        sandboxState:
          type: object
          nullable: true
          additionalProperties: true
          description: Sandbox runtime state (Vercel Sandbox).
        lifecycleState:
          type: string
          nullable: true
          enum:
            - provisioning
            - active
            - hibernating
            - hibernated
            - restoring
            - archived
            - failed
          description: Lifecycle orchestration state for the sandbox.
        lifecycleVersion:
          type: integer
          description: Optimistic concurrency token for lifecycle transitions.
        lastActivityAt:
          type: string
          format: date-time
          nullable: true
        sandboxExpiresAt:
          type: string
          format: date-time
          nullable: true
        hibernateAfter:
          type: string
          format: date-time
          nullable: true
        lifecycleRunId:
          type: string
          nullable: true
        lifecycleError:
          type: string
          nullable: true
        linesAdded:
          type: integer
          nullable: true
          description: >-
            Lines added across the session's diff. Defaults to 0; null when
            stats have not been computed.
        linesRemoved:
          type: integer
          nullable: true
          description: >-
            Lines removed across the session's diff. Defaults to 0; null when
            stats have not been computed.
        snapshotUrl:
          type: string
          nullable: true
        snapshotCreatedAt:
          type: string
          format: date-time
          nullable: true
        snapshotSizeBytes:
          type: integer
          nullable: true
        cachedDiff:
          type: object
          nullable: true
          additionalProperties: true
        cachedDiffUpdatedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        artistId:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Artist account id this session was created in the context of, or
            `null` when no artist was associated. Set via `POST /api/sessions {
            artistId }`; surfaces here for clients (e.g. the chat sidebar) that
            filter sessions/chats by artist.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer

````