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

# List sessions

> Returns a collection of sessions.

Required API key scopes: any of `sessions:read`, `sessions:all`, `all:read`, `all:all`.



## OpenAPI

````yaml /coding-agent-api/openapi.json get /api/v1/sessions
openapi: 3.1.0
info:
  title: Agen Coding Agent API
  version: 1.0.0
servers:
  - url: https://api.agenhq.com
security: []
paths:
  /api/v1/sessions:
    get:
      tags:
        - Sessions
      summary: List sessions
      description: >-
        Returns a collection of sessions.


        Required API key scopes: any of `sessions:read`, `sessions:all`,
        `all:read`, `all:all`.
      operationId: listSessions
      parameters:
        - schema:
            type: string
          in: query
          name: status
          required: false
          description: Filter sessions by lifecycle status.
        - schema:
            type: string
          in: query
          name: user_id
          required: false
          description: Filter sessions to those created by a specific user.
        - schema:
            type: string
          in: query
          name: include
          required: false
          description: >-
            Include additional computed fields in each session item, for example
            `mr_pipeline_summary`.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionsList'
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - statusCode
                  - code
                  - error
                  - message
                properties:
                  statusCode:
                    type: number
                  code:
                    type: string
                  error:
                    type: string
                  message:
                    type: string
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
      security:
        - apiKey: []
components:
  schemas:
    SessionsList:
      type: object
      required:
        - items
        - next_cursor
      properties:
        items:
          type: array
          items:
            type: object
            required:
              - id
              - title
              - workspace_id
              - user_id
              - branch_name
              - auto_commit
              - status
              - origin
              - created_at
              - updated_at
            properties:
              id:
                description: The unique identifier of the session inside Agen.
                type: string
              title:
                description: >-
                  A short title generated from the initial prompt that helps
                  identify the session.
                type: string
              workspace_id:
                description: The workspace that owns this session.
                type: string
              user_id:
                description: The user who created the session.
                type: string
              sandbox_id:
                anyOf:
                  - description: The sandbox currently assigned to this session.
                    type: string
                  - type: 'null'
              branch_name:
                anyOf:
                  - description: The git branch Agen should use for this session.
                    type: string
                  - type: 'null'
              auto_commit:
                default: false
                description: >-
                  Whether Agen should automatically create git commits while
                  working in the session.
                type: boolean
              model:
                description: >-
                  The LLM model code to use for the session, if you want to
                  override the workspace default.
                type: string
              status:
                description: The current lifecycle status of the session.
                type: string
              agent_status:
                description: >-
                  The current execution status of the coding agent inside the
                  session.
                type: string
              merged_at:
                anyOf:
                  - description: >-
                      When the session changes were merged, if the related merge
                      request has been merged.
                    type: string
                  - type: 'null'
              origin:
                description: >-
                  Where the session was created from, such as the app, API, or a
                  deep work flow.
                type: string
              deep_work_id:
                anyOf:
                  - description: >-
                      The related deep work item ID, if this session was created
                      from a deep work flow.
                    type: string
                  - type: 'null'
              created_at:
                description: When the session was created.
                format: date-time
                type: string
              updated_at:
                description: When the session was last updated.
                format: date-time
                type: string
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````