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

# Retrieve a session

> Retrieve a session you have permission to access.



## OpenAPI

````yaml https://api.tembo.io/public-api/openapi/public get /v1/sessions/{sessionId}
openapi: 3.1.0
info:
  title: Tembo Public API
  description: >-
    Manage agents, sessions, repositories, and organization resources with the
    Tembo API.
  version: 1.0.0
servers:
  - url: https://api.tembo.io
    description: Tembo API
  - url: https://{deployment-origin}/api/public-api
    description: Self-hosted Tembo
    variables:
      deployment-origin:
        default: tembo.example.com
        description: Hostname of your self-hosted Tembo deployment
security: []
paths:
  /v1/sessions/{sessionId}:
    get:
      tags:
        - Sessions
      summary: Retrieve a session
      description: Retrieve a session you have permission to access.
      operationId: retrieveSession
      parameters:
        - in: path
          name: sessionId
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          required: true
      responses:
        '200':
          description: Retrieve a session
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    type:
                      - string
                      - 'null'
                  agentId:
                    anyOf:
                      - type: string
                        format: uuid
                        pattern: >-
                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      - type: 'null'
                  artifactType:
                    anyOf:
                      - type: string
                        enum:
                          - PullRequest
                          - ToolCall
                          - Plan
                          - Response
                          - File
                          - Service
                          - Source
                      - type: 'null'
                  baseBranch:
                    type:
                      - string
                      - 'null'
                  branchName:
                    type:
                      - string
                      - 'null'
                  createdAt:
                    type: string
                    format: date-time
                    pattern: >-
                      ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                  externalId:
                    type:
                      - string
                      - 'null'
                  externalUrl:
                    type:
                      - string
                      - 'null'
                  id:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  kind:
                    type: string
                  lastQueuedAt:
                    anyOf:
                      - type: string
                        format: date-time
                        pattern: >-
                          ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                      - type: 'null'
                  lastSeenAt:
                    type: string
                    format: date-time
                    pattern: >-
                      ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                  level:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  mode:
                    default: normal
                    type: string
                    enum:
                      - normal
                      - planning
                  parentSessionId:
                    anyOf:
                      - type: string
                        format: uuid
                        pattern: >-
                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      - type: 'null'
                    description: The session whose agent created this session.
                  projectId:
                    type:
                      - string
                      - 'null'
                  sandboxSize:
                    anyOf:
                      - type: string
                        enum:
                          - nano
                          - micro
                          - small
                          - medium
                          - large
                          - xl
                          - xxl
                          - ultra
                      - type: 'null'
                  sessionType:
                    default: Chat
                    type: string
                    enum:
                      - Chat
                      - Terminal
                  targetBranch:
                    type:
                      - string
                      - 'null'
                  title:
                    type: string
                  updatedAt:
                    type: string
                    format: date-time
                    pattern: >-
                      ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                  visibility:
                    type: string
                    enum:
                      - private
                      - public
                    description: >-
                      Deprecated: `private` when shared with no one, `public`
                      when shared with anyone. List the session’s shares for its
                      exact audiences.
                    deprecated: true
                  artifacts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        type:
                          type: string
                          enum:
                            - PullRequest
                            - ToolCall
                            - Plan
                            - Response
                            - File
                            - Service
                            - Source
                        createdAt:
                          type: string
                          format: date-time
                          pattern: >-
                            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                        updatedAt:
                          type: string
                          format: date-time
                          pattern: >-
                            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                        pullRequests:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                                pattern: >-
                                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              url:
                                type: string
                                format: uri
                              title:
                                type:
                                  - string
                                  - 'null'
                              status:
                                type: string
                                enum:
                                  - open
                                  - merged
                                  - closed
                              isDraft:
                                type: boolean
                              sourceBranch:
                                type:
                                  - string
                                  - 'null'
                              createdAt:
                                type: string
                                format: date-time
                                pattern: >-
                                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                              agent:
                                type:
                                  - string
                                  - 'null'
                              diff:
                                anyOf:
                                  - type: object
                                    properties:
                                      additions:
                                        type: integer
                                        minimum: 0
                                        maximum: 9007199254740991
                                      deletions:
                                        type: integer
                                        minimum: 0
                                        maximum: 9007199254740991
                                      data:
                                        type: string
                                        maxLength: 1000000
                                    additionalProperties: false
                                  - type: 'null'
                              updatedAt:
                                type: string
                                format: date-time
                                pattern: >-
                                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                              baseBranch:
                                anyOf:
                                  - type: string
                                    maxLength: 500
                                  - type: 'null'
                              headSha:
                                anyOf:
                                  - type: string
                                    maxLength: 200
                                  - type: 'null'
                              author:
                                anyOf:
                                  - type: object
                                    properties:
                                      avatarUrl:
                                        anyOf:
                                          - type: string
                                            format: uri
                                          - type: 'null'
                                      login:
                                        anyOf:
                                          - type: string
                                            maxLength: 500
                                          - type: 'null'
                                    required:
                                      - avatarUrl
                                      - login
                                    additionalProperties: false
                                  - type: 'null'
                              codeRepository:
                                anyOf:
                                  - type: object
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                        pattern: >-
                                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      name:
                                        type: string
                                      owner:
                                        type:
                                          - string
                                          - 'null'
                                      baseBranch:
                                        type:
                                          - string
                                          - 'null'
                                      provider:
                                        type: string
                                    required:
                                      - id
                                      - name
                                      - owner
                                      - baseBranch
                                      - provider
                                    additionalProperties: false
                                  - type: 'null'
                            required:
                              - id
                              - url
                              - title
                              - status
                              - isDraft
                              - sourceBranch
                              - createdAt
                              - agent
                              - diff
                              - updatedAt
                              - baseBranch
                              - headSha
                              - author
                              - codeRepository
                            additionalProperties: false
                      required:
                        - id
                        - type
                        - createdAt
                        - updatedAt
                        - pullRequests
                      additionalProperties: false
                  automaticSizing:
                    type: boolean
                    description: Whether the session VM is sized automatically.
                  description:
                    type:
                      - string
                      - 'null'
                  diffSummary:
                    anyOf:
                      - type: object
                        properties:
                          additions:
                            type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          deletions:
                            type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                        required:
                          - additions
                          - deletions
                        additionalProperties: false
                      - type: 'null'
                  folderId:
                    anyOf:
                      - type: string
                        format: uuid
                        pattern: >-
                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      - type: 'null'
                    description: >-
                      Sidebar folder the authenticated user filed this session
                      in.
                  htmlUrl:
                    type: string
                    format: uri
                  isPinned:
                    type: boolean
                  project:
                    anyOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                            pattern: >-
                              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          name:
                            type: string
                          icon:
                            type: string
                            enum:
                              - folder
                              - code
                              - terminal
                              - book
                              - brain
                              - bug
                              - building
                              - cloud
                              - globe
                              - idea
                              - tools
                              - magic
                              - processor
                              - sandbox
                              - server
                              - tasks
                              - tactics
                              - images
                              - database
                              - api
                              - mobile
                              - package
                          color:
                            type: string
                            enum:
                              - neutral
                              - red
                              - orange
                              - yellow
                              - green
                              - teal
                              - blue
                              - purple
                              - pink
                        required:
                          - id
                          - name
                          - icon
                          - color
                        additionalProperties: false
                      - type: 'null'
                  sessionSource:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        pattern: >-
                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      name:
                        type: string
                      type:
                        type: string
                      repositories:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              pattern: >-
                                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            name:
                              type: string
                            provider:
                              type: string
                          required:
                            - id
                            - name
                            - provider
                          additionalProperties: false
                    required:
                      - id
                      - name
                      - type
                      - repositories
                    additionalProperties: false
                  sourcePullRequest:
                    anyOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                            pattern: >-
                              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          url:
                            type: string
                            format: uri
                          title:
                            type:
                              - string
                              - 'null'
                          status:
                            type: string
                            enum:
                              - open
                              - merged
                              - closed
                          isDraft:
                            type: boolean
                        required:
                          - id
                          - url
                          - title
                          - status
                          - isDraft
                        additionalProperties: false
                      - type: 'null'
                  state:
                    type: object
                    properties:
                      current:
                        type: string
                        enum:
                          - inProgress
                          - queued
                          - completed
                          - failed
                          - cancelled
                      isQueued:
                        type: boolean
                      isCancelled:
                        type: boolean
                      isCompleted:
                        type: boolean
                      isFailed:
                        type: boolean
                      inProgress:
                        type: boolean
                    required:
                      - isQueued
                      - isCancelled
                      - isCompleted
                      - isFailed
                      - inProgress
                    additionalProperties: false
                required:
                  - agent
                  - agentId
                  - artifactType
                  - baseBranch
                  - branchName
                  - createdAt
                  - externalId
                  - externalUrl
                  - id
                  - kind
                  - lastQueuedAt
                  - lastSeenAt
                  - level
                  - mode
                  - parentSessionId
                  - projectId
                  - sandboxSize
                  - sessionType
                  - targetBranch
                  - title
                  - updatedAt
                  - visibility
                  - artifacts
                  - automaticSizing
                  - description
                  - diffSummary
                  - folderId
                  - htmlUrl
                  - isPinned
                  - project
                  - sessionSource
                  - sourcePullRequest
                  - state
                additionalProperties: false
        '400':
          description: >-
            Invalid request or missing required organization or user
            information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '401':
          description: The session is private
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '403':
          description: The caller is not permitted to perform this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '404':
          description: Session resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '409':
          description: Session operation conflicts with existing data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '500':
          description: Session operation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '502':
          description: Session runtime or provider operation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
      security:
        - apiKey: []
      x-codeSamples:
        - lang: typescript
          label: TypeScript SDK
          source: >
            import Tembo from '@tembo-io/sdk';


            const client = new Tembo();


            const session = await
            client.sessions.retrieve('7c9e6679-7425-40de-944b-e07fc1f90ae7');
        - lang: rust
          label: Rust SDK
          source: |
            use tembo_rs::*;

            let client = Tembo::from_env()?;

            let response = client
                .sessions()
                .retrieve("7c9e6679-7425-40de-944b-e07fc1f90ae7")
                .send()
                .await?;
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.