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

# Expire a session

> Ends the session now instead of after 72 hours without use: its code, invite link and session token stop working, a running task stops and its computer is disconnected. Tasks and recordings are kept (delete the session to remove them). Expiring an expired session does nothing. Recorded in the audit log.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/sessions/{session_id}/expire
openapi: 3.1.0
info:
  title: GuidingHand API
  version: 1.0.0
  description: >-
    Create sessions (an invite link with a code for the person at the computer),
    run tasks on their computer with one of your agents, follow them, answer
    their questions and approvals, and fetch history and recordings.
servers:
  - url: https://guidinghand.ai
    description: Production
  - url: https://dev.guidinghand.ai
    description: Development (Stripe test mode)
security:
  - bearerAuth: []
tags:
  - name: Agents
  - name: Sessions
  - name: Tasks
  - name: Webhooks
paths:
  /v1/sessions/{session_id}/expire:
    parameters:
      - name: session_id
        in: path
        required: true
        description: The session’s code, e.g. `K7QM-24XP`.
        schema:
          type: string
    post:
      tags:
        - Sessions
      summary: Expire a session
      description: >-
        Ends the session now instead of after 72 hours without use: its code,
        invite link and session token stop working, a running task stops and its
        computer is disconnected. Tasks and recordings are kept (delete the
        session to remove them). Expiring an expired session does nothing.
        Recorded in the audit log.
      operationId: expireSession
      responses:
        '200':
          description: The session, as it is now
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/E401'
        '404':
          $ref: '#/components/responses/E404'
components:
  schemas:
    Session:
      type: object
      properties:
        object:
          const: session
        session_id:
          type: string
          example: K7QM-24XP
        code:
          type: string
          example: K7QM-24XP
        agent_id:
          type: string
        invite_url:
          type: string
          example: https://guidinghand.ai/acme/billing/K7QM-24XP
        status:
          type: string
          enum:
            - waiting
            - connected
            - disconnected
            - expired
          description: >-
            `waiting`: no computer has used the code yet. `connected`: its
            computer is online now. `disconnected`: its computer went offline,
            or the team disconnected it. `expired`: unused for 72 hours, or
            expired by the team; the code and token no longer work.
        device:
          $ref: '#/components/schemas/Device'
        metadata:
          $ref: '#/components/schemas/Metadata'
        created_at:
          type: string
          format: date-time
        paired_at:
          type:
            - string
            - 'null'
          format: date-time
        last_active_at:
          type: string
          format: date-time
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the code expires if it stays unused (null while connected), or
            when it was expired.
        task_count:
          type: integer
        latest_task_id:
          type:
            - string
            - 'null'
    Device:
      type:
        - object
        - 'null'
      properties:
        os:
          type: string
          enum:
            - mac
            - windows
            - linux
            - unknown
        name:
          type:
            - string
            - 'null'
        width:
          type: integer
        height:
          type: integer
        app_version:
          type:
            - string
            - 'null'
    Metadata:
      type: object
      additionalProperties:
        type: string
        maxLength: 500
      maxProperties: 50
      description: >-
        Your own ids and labels (e.g. a ticket or customer id), returned as
        given.
      example:
        customer_id: cus_42
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              enum:
                - invalid_request
                - authentication
                - payment_required
                - permission
                - not_found
                - conflict
                - rate_limit
                - server_error
            message:
              type: string
            code:
              type: string
              description: >-
                Why an answer or decision was refused (on `/respond`):
                `already_answered` (someone answered or decided first: see
                `answered_by`) or `not_pending` (that question or approval isn’t
                open any more). The GuidingHand app hears two more, which the
                API never returns: `customer_answers_off` and
                `customer_approvals_off` (the agent keeps its questions or
                approvals for your team).
            answered_by:
              type: string
              enum:
                - customer
                - operator
                - timeout
              description: >-
                With `already_answered`: who answered or decided first
                (`customer`: the person at the computer; `timeout`: nobody
                decided an approval within the agent’s
                `approval_timeout_minutes`, so it was denied).
  responses:
    E401:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E404:
      description: Not found in this org.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An org API key (`gh_live_…`) from Settings → API keys in the console.

````