> ## 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.

# Get the session timeline events

> Returns the events that make up the session timeline shown to users. This includes user and agent messages, as well as progress events emitted while the agent is working, such as file operations, planning updates, repository actions, and other execution steps. Clients can use these events both to render the conversation and to track the agent's progress through the session.

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/{sessionId}/events
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/{sessionId}/events:
    get:
      tags:
        - Sessions
      summary: Get the session timeline events
      description: >-
        Returns the events that make up the session timeline shown to users.
        This includes user and agent messages, as well as progress events
        emitted while the agent is working, such as file operations, planning
        updates, repository actions, and other execution steps. Clients can use
        these events both to render the conversation and to track the agent's
        progress through the session.


        Required API key scopes: any of `sessions:read`, `sessions:all`,
        `all:read`, `all:all`.
      operationId: getSessionEvents
      parameters:
        - schema:
            minLength: 1
            type: string
          in: path
          name: sessionId
          required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - id
                    - session_id
                    - type
                    - payload
                    - status
                    - client_id
                    - session_goal_id
                    - session_task_id
                    - created_at
                    - updated_at
                  properties:
                    id:
                      type: string
                    session_id:
                      type: string
                    type:
                      enum:
                        - user_message
                        - agent_message
                        - system_message
                        - session_finished
                        - session_closed
                        - merge_request_merged
                        - merge_request_closed
                        - agent_file_tree_browse
                        - agent_file_read
                        - agent_file_edit
                        - agent_file_create
                        - agent_file_remove
                        - agent_file_move
                        - agent_file_copy
                        - agent_file_read_range
                        - agent_read_around_match
                        - agent_search_files
                        - agent_search_files_v2
                        - agent_plan_execution_update
                        - agent_ask_user
                        - user_ask_user_response
                        - agent_branch_diff
                        - agent_uncommitted_changes
                        - agent_conflict_state
                        - agent_check_target_branch_mergeability
                        - agent_merge_remote_branch
                        - agent_pull_from_remote
                        - agent_push_to_remote
                        - agent_abort_conflict_resolution
                        - agent_rollback_uncommitted_changes
                        - agent_http_request
                        - agent_web_browse
                        - agent_run_repository_command
                        - agent_alert_created
                      type: string
                    payload:
                      anyOf:
                        - description: >-
                            A message sent by the user to the agent within a
                            session. This is the payload created by the send
                            message endpoint.
                          type: object
                          required:
                            - type
                            - message
                          properties:
                            type:
                              type: string
                              enum:
                                - user_message
                            message:
                              type: string
                        - description: >-
                            A chat message emitted by the agent during a session
                            and shown in the session timeline.
                          type: object
                          required:
                            - type
                            - message
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_message
                            message:
                              type: string
                        - description: >-
                            A system-generated informational message shown in
                            the session timeline.
                          type: object
                          required:
                            - type
                            - message
                          properties:
                            type:
                              type: string
                              enum:
                                - system_message
                            message:
                              type: string
                        - anyOf:
                            - description: >-
                                Indicates that the session was finished,
                                including the actor who finished it.
                              type: object
                              required:
                                - type
                                - actor
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - session_finished
                                actor:
                                  type: object
                                  required:
                                    - id
                                  properties:
                                    id:
                                      type: string
                                    first_name:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    last_name:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    email:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                            - description: >-
                                Indicates that the session was closed, including
                                the actor who closed it.
                              type: object
                              required:
                                - type
                                - actor
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - session_closed
                                actor:
                                  type: object
                                  required:
                                    - id
                                  properties:
                                    id:
                                      type: string
                                    first_name:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    last_name:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    email:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                            - description: >-
                                Indicates that the session merge request was
                                merged, including the actor who merged it.
                              type: object
                              required:
                                - type
                                - actor
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - merge_request_merged
                                actor:
                                  type: object
                                  required:
                                    - id
                                  properties:
                                    id:
                                      type: string
                                    first_name:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    last_name:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    email:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                            - description: >-
                                Indicates that the session merge request was
                                closed without merging, including the actor who
                                closed it.
                              type: object
                              required:
                                - type
                                - actor
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - merge_request_closed
                                actor:
                                  type: object
                                  required:
                                    - id
                                  properties:
                                    id:
                                      type: string
                                    first_name:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    last_name:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    email:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                        - description: >-
                            Indicates that the agent browsed the repository file
                            tree at a given path.
                          type: object
                          required:
                            - type
                            - repository_id
                            - path
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_file_tree_browse
                            repository_id:
                              type: string
                            path:
                              type: string
                        - description: >-
                            Indicates that the agent read one or more files from
                            a repository.
                          type: object
                          required:
                            - type
                            - repository_id
                            - paths
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_file_read
                            repository_id:
                              type: string
                            paths:
                              type: array
                              items:
                                type: string
                        - anyOf:
                            - description: >-
                                Indicates that the agent edited an existing file
                                and includes the resulting diff.
                              type: object
                              required:
                                - type
                                - repository_id
                                - file_path
                                - diff
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - agent_file_edit
                                repository_id:
                                  type: string
                                file_path:
                                  type: string
                                diff:
                                  type: string
                            - description: >-
                                Indicates that the agent created a new file and
                                includes the resulting diff.
                              type: object
                              required:
                                - type
                                - repository_id
                                - file_path
                                - diff
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - agent_file_create
                                repository_id:
                                  type: string
                                file_path:
                                  type: string
                                diff:
                                  type: string
                        - description: >-
                            Indicates that the agent removed a file from a
                            repository.
                          type: object
                          required:
                            - type
                            - repository_id
                            - file_path
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_file_remove
                            repository_id:
                              type: string
                            file_path:
                              type: string
                        - anyOf:
                            - description: >-
                                Indicates that the agent moved or renamed a file
                                within a repository.
                              type: object
                              required:
                                - type
                                - repository_id
                                - source_path
                                - destination_path
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - agent_file_move
                                repository_id:
                                  type: string
                                source_path:
                                  type: string
                                destination_path:
                                  type: string
                                diff:
                                  type: string
                            - description: >-
                                Indicates that the agent copied a file within a
                                repository.
                              type: object
                              required:
                                - type
                                - repository_id
                                - source_path
                                - destination_path
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - agent_file_copy
                                repository_id:
                                  type: string
                                source_path:
                                  type: string
                                destination_path:
                                  type: string
                                diff:
                                  type: string
                        - description: >-
                            Indicates that the agent read a specific line range
                            from a file.
                          type: object
                          required:
                            - type
                            - repository_id
                            - path
                            - start_line
                            - end_line
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_file_read_range
                            repository_id:
                              type: string
                            path:
                              type: string
                            start_line:
                              type: number
                            end_line:
                              type: number
                        - description: >-
                            Indicates that the agent searched file contents and
                            returned surrounding context for the matches.
                          type: object
                          required:
                            - type
                            - repository_id
                            - query
                            - path
                            - matches
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_read_around_match
                            repository_id:
                              type: string
                            query:
                              type: string
                            path:
                              type: string
                            include:
                              type: string
                            matches:
                              type: array
                              items:
                                type: object
                                required:
                                  - file
                                  - match_line
                                  - content
                                properties:
                                  file:
                                    type: string
                                  match_line:
                                    type: number
                                  content:
                                    type: array
                                    items:
                                      type: object
                                      required:
                                        - line
                                        - content
                                      properties:
                                        line:
                                          type: number
                                        content:
                                          type: string
                        - description: >-
                            Indicates that the agent searched files for a query
                            and returned matching results.
                          type: object
                          required:
                            - type
                            - repository_id
                            - query
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_search_files
                            repository_id:
                              type: string
                            query:
                              type: string
                            path:
                              type: string
                            include:
                              type: string
                            results:
                              type: array
                              items:
                                type: object
                                required:
                                  - file
                                  - line
                                  - content
                                properties:
                                  file:
                                    type: string
                                  line:
                                    type: number
                                  content:
                                    type: string
                        - description: >-
                            Indicates that the agent ran multiple file searches
                            and returned grouped results for each query item.
                          type: object
                          required:
                            - type
                            - repository_id
                            - items
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_search_files_v2
                            repository_id:
                              type: string
                            items:
                              type: array
                              items:
                                type: object
                                required:
                                  - query
                                properties:
                                  query:
                                    type: string
                                  path:
                                    type: string
                                  include:
                                    type: string
                                  results:
                                    type: array
                                    items:
                                      type: object
                                      required:
                                        - file
                                        - line
                                        - content
                                      properties:
                                        file:
                                          type: string
                                        line:
                                          type: number
                                        content:
                                          type: string
                        - description: >-
                            Indicates that the agent created or updated its
                            execution plan, including the current goal and task
                            list.
                          type: object
                          required:
                            - type
                            - goal_title
                            - goal_id
                            - tasks
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_plan_execution_update
                            goal_title:
                              type: string
                            goal_id:
                              type: string
                            tasks:
                              type: array
                              items:
                                type: object
                                required:
                                  - id
                                  - title
                                  - status
                                properties:
                                  id:
                                    type: string
                                  title:
                                    type: string
                                  status:
                                    type: string
                        - description: >-
                            Indicates that the agent asked the user one or more
                            multiple-choice clarification questions.
                          type: object
                          required:
                            - type
                            - questions
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_ask_user
                            questions:
                              type: array
                              items:
                                type: object
                                required:
                                  - question
                                  - topic
                                  - options
                                properties:
                                  question:
                                    type: string
                                  topic:
                                    type: string
                                  options:
                                    type: array
                                    items:
                                      type: string
                        - description: >-
                            Indicates that the user responded to a previous
                            ask-user question set from the agent.
                          type: object
                          required:
                            - type
                            - answers
                          properties:
                            type:
                              type: string
                              enum:
                                - user_ask_user_response
                            answers:
                              type: array
                              items:
                                type: object
                                required:
                                  - topic
                                  - answer
                                properties:
                                  topic:
                                    type: string
                                  answer:
                                    type: string
                        - description: >-
                            Indicates that the agent inspected branch changes,
                            either by listing changed files or returning a diff
                            for a specific file.
                          type: object
                          required:
                            - type
                            - repository_id
                            - action
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_branch_diff
                            repository_id:
                              type: string
                            action:
                              anyOf:
                                - type: string
                                  enum:
                                    - list_files
                                - type: string
                                  enum:
                                    - file_diff
                            files:
                              type: array
                              items:
                                type: object
                                required:
                                  - path
                                properties:
                                  path:
                                    type: string
                            file_path:
                              type: string
                            diff:
                              type: string
                        - description: >-
                            Indicates that the agent inspected the repository
                            working tree and returned staged, unstaged,
                            untracked, and conflict information.
                          type: object
                          required:
                            - type
                            - repository_id
                            - branch
                            - clean
                            - staged
                            - unstaged
                            - untracked
                            - conflict_state
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_uncommitted_changes
                            repository_id:
                              type: string
                            branch:
                              type: string
                            clean:
                              type: boolean
                            staged:
                              type: object
                              required:
                                - added
                                - modified
                                - deleted
                                - renamed
                              properties:
                                added:
                                  type: array
                                  items:
                                    type: string
                                modified:
                                  type: array
                                  items:
                                    type: string
                                deleted:
                                  type: array
                                  items:
                                    type: string
                                renamed:
                                  type: array
                                  items:
                                    type: object
                                    required:
                                      - from
                                      - to
                                    properties:
                                      from:
                                        type: string
                                      to:
                                        type: string
                            unstaged:
                              type: object
                              required:
                                - added
                                - modified
                                - deleted
                                - renamed
                              properties:
                                added:
                                  type: array
                                  items:
                                    type: string
                                modified:
                                  type: array
                                  items:
                                    type: string
                                deleted:
                                  type: array
                                  items:
                                    type: string
                                renamed:
                                  type: array
                                  items:
                                    type: object
                                    required:
                                      - from
                                      - to
                                    properties:
                                      from:
                                        type: string
                                      to:
                                        type: string
                            untracked:
                              type: array
                              items:
                                type: string
                            conflict_state:
                              type: object
                              required:
                                - conflicted
                                - state
                              properties:
                                conflicted:
                                  type: array
                                  items:
                                    type: string
                                state:
                                  type: object
                                  required:
                                    - merge
                                    - rebase
                                    - cherry_pick
                                    - revert
                                  properties:
                                    merge:
                                      type: boolean
                                    rebase:
                                      type: boolean
                                    cherry_pick:
                                      type: boolean
                                    revert:
                                      type: boolean
                            diff:
                              type: object
                              required:
                                - staged
                                - unstaged
                                - truncated
                              properties:
                                staged:
                                  type: string
                                unstaged:
                                  type: string
                                truncated:
                                  type: boolean
                        - description: >-
                            Indicates that the agent checked whether the
                            repository is currently in a git conflict state.
                          type: object
                          required:
                            - type
                            - repository_id
                            - branch
                            - has_conflicts
                            - conflicted_files
                            - operation_state
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_conflict_state
                            repository_id:
                              type: string
                            branch:
                              type: string
                            has_conflicts:
                              type: boolean
                            conflicted_files:
                              type: array
                              items:
                                type: string
                            operation_state:
                              type: object
                              required:
                                - merge
                                - rebase
                                - cherry_pick
                                - revert
                              properties:
                                merge:
                                  type: boolean
                                rebase:
                                  type: boolean
                                cherry_pick:
                                  type: boolean
                                revert:
                                  type: boolean
                        - description: >-
                            Indicates that the agent checked whether the current
                            branch can be merged with the target branch and
                            whether conflicts would occur.
                          type: object
                          required:
                            - type
                            - repository_id
                            - current_branch
                            - target_branch
                            - mergeable
                            - has_conflicts
                            - conflicted_files
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_check_target_branch_mergeability
                            repository_id:
                              type: string
                            current_branch:
                              type: string
                            target_branch:
                              type: string
                            mergeable:
                              type: boolean
                            has_conflicts:
                              type: boolean
                            conflicted_files:
                              type: array
                              items:
                                type: string
                        - description: >-
                            Indicates that the agent merged the target branch
                            into the current branch to reproduce or resolve
                            incoming changes.
                          type: object
                          required:
                            - type
                            - repository_id
                            - current_branch
                            - target_branch
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_merge_remote_branch
                            repository_id:
                              type: string
                            current_branch:
                              type: string
                            target_branch:
                              type: string
                        - description: >-
                            Indicates that the agent pulled changes from the
                            remote branch and rebased the local branch onto
                            them.
                          type: object
                          required:
                            - type
                            - repository_id
                            - rebased
                            - message
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_pull_from_remote
                            repository_id:
                              type: string
                            rebased:
                              type: boolean
                            message:
                              type: string
                            branch:
                              type: string
                            before_sha:
                              anyOf:
                                - type: string
                                - type: 'null'
                            after_sha:
                              anyOf:
                                - type: string
                                - type: 'null'
                            remote:
                              type: string
                        - description: >-
                            Indicates that the agent pushed committed changes
                            from the current branch to the remote repository.
                          type: object
                          required:
                            - type
                            - repository_id
                            - pushed
                            - message
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_push_to_remote
                            repository_id:
                              type: string
                            pushed:
                              type: boolean
                            message:
                              type: string
                            branch:
                              type: string
                            remote:
                              type: string
                            remote_ref:
                              type: string
                        - description: >-
                            Indicates that the agent aborted an in-progress
                            merge, rebase, cherry-pick, or revert conflict
                            resolution flow.
                          type: object
                          required:
                            - type
                            - repository_id
                            - aborted
                            - aborted_operation
                            - message
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_abort_conflict_resolution
                            repository_id:
                              type: string
                            aborted:
                              type: boolean
                            aborted_operation:
                              anyOf:
                                - type: string
                                  enum:
                                    - merge
                                - type: string
                                  enum:
                                    - rebase
                                - type: string
                                  enum:
                                    - cherry-pick
                                - type: string
                                  enum:
                                    - revert
                                - type: 'null'
                            message:
                              type: string
                        - description: >-
                            Indicates that the agent discarded local uncommitted
                            changes for the requested scope.
                          type: object
                          required:
                            - type
                            - repository_id
                            - scope
                            - rolled_back_paths
                            - removed_untracked_paths
                            - message
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_rollback_uncommitted_changes
                            repository_id:
                              type: string
                            scope:
                              anyOf:
                                - type: string
                                  enum:
                                    - unstaged
                                - type: string
                                  enum:
                                    - staged
                                - type: string
                                  enum:
                                    - all
                            rolled_back_paths:
                              type: array
                              items:
                                type: string
                            removed_untracked_paths:
                              type: array
                              items:
                                type: string
                            message:
                              type: string
                        - description: >-
                            Indicates that the agent made an HTTP request to an
                            external URL.
                          type: object
                          required:
                            - type
                            - url
                            - method
                            - status
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_http_request
                            url:
                              type: string
                            method:
                              type: string
                            status:
                              type: number
                        - description: >-
                            Indicates that the agent fetched and browsed a web
                            page.
                          type: object
                          required:
                            - type
                            - url
                            - status
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_web_browse
                            url:
                              type: string
                            status:
                              type: number
                        - description: >-
                            Indicates that the agent ran a command in a
                            repository and includes the command output.
                          type: object
                          required:
                            - type
                            - repository_id
                            - executable
                            - args
                            - exit_code
                            - stdout
                            - stderr
                            - output
                            - truncated
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_run_repository_command
                            repository_id:
                              type: string
                            executable:
                              enum:
                                - node
                                - npm
                                - npx
                                - yarn
                              type: string
                            args:
                              type: array
                              items:
                                type: string
                            working_directory:
                              type: string
                            exit_code:
                              type: number
                            stdout:
                              type: string
                            stderr:
                              type: string
                            output:
                              type: string
                            truncated:
                              type: boolean
                        - description: >-
                            Indicates that the agent created an alert that
                            requires human attention or follow-up.
                          type: object
                          required:
                            - type
                            - alert_id
                            - level
                            - status
                            - title
                          properties:
                            type:
                              type: string
                              enum:
                                - agent_alert_created
                            alert_id:
                              type: string
                            level:
                              type: string
                            status:
                              type: string
                            title:
                              type: string
                            description:
                              anyOf:
                                - type: string
                                - type: 'null'
                            fingerprint:
                              anyOf:
                                - type: string
                                - type: 'null'
                            repository_id:
                              anyOf:
                                - type: string
                                - type: 'null'
                            repository_name:
                              anyOf:
                                - type: string
                                - type: 'null'
                            merge_request_id:
                              anyOf:
                                - type: string
                                - type: 'null'
                            scheduled_agent_run_id:
                              anyOf:
                                - type: string
                                - type: 'null'
                            occurrence_count:
                              type: number
                    status:
                      enum:
                        - completed
                        - queued
                        - processing
                        - canceled
                      type: string
                    client_id:
                      anyOf:
                        - type: string
                        - type: 'null'
                    session_goal_id:
                      anyOf:
                        - type: string
                        - type: 'null'
                    session_task_id:
                      anyOf:
                        - type: string
                        - type: 'null'
                    created_at:
                      type: string
                    updated_at:
                      type: string
        '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:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````