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

# Read a task's recorded diff

> Reads the newest diff recorded of a task's work tree: every file it changed against its base branch, each text with its hunks or omitted with why, when it was recorded, and whether the latest attempt to record it failed. It asks nothing of the task's machine, so it answers the same while that machine is asleep.

Use this tool when you need to:
- Show a task's changes without its machine at hand, as the diff pane does for a task on a computer that is not connected

Examples:
- GET /tasks/{taskID}/diff

Hints:
- state is recorded, with the diff, or not_recorded. A task whose machine records no diff, every sandbox task's among them, is not_recorded, never refused.
- recorded_at is when the machine observed the diff shown.
- last_failure is the latest attempt when it failed, with when and why: set when it is newer than the recorded diff, or when none was ever recorded; null otherwise. A failure never replaces a recorded diff.
- A file's status is a word git gives and no closed list: show one you do not know as modified. An omitted file shows its reason's message in place of its content; a reason's code is no closed list either.
- The machine records the diff when a turn of one of the task's chats ends; each recording kept ticks the task.
- Whoever reads the task reads its diff: a checkout's task is its person's alone, and another member of the organization finds no such task (404); a work tree Aether made is the organization's. A billing member is refused with 403 org_role_insufficient, a suspended organization with 403 org_suspended; 503 when the membership check is unavailable.



## OpenAPI

````yaml api-reference/openapi.json GET /tasks/{taskID}/diff
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /tasks/{taskID}/diff:
    get:
      tags:
        - tasks
      summary: Read a task's recorded diff
      description: >-
        Reads the newest diff recorded of a task's work tree: every file it
        changed against its base branch, each text with its hunks or omitted
        with why, when it was recorded, and whether the latest attempt to record
        it failed. It asks nothing of the task's machine, so it answers the same
        while that machine is asleep.


        Use this tool when you need to:

        - Show a task's changes without its machine at hand, as the diff pane
        does for a task on a computer that is not connected


        Examples:

        - GET /tasks/{taskID}/diff


        Hints:

        - state is recorded, with the diff, or not_recorded. A task whose
        machine records no diff, every sandbox task's among them, is
        not_recorded, never refused.

        - recorded_at is when the machine observed the diff shown.

        - last_failure is the latest attempt when it failed, with when and why:
        set when it is newer than the recorded diff, or when none was ever
        recorded; null otherwise. A failure never replaces a recorded diff.

        - A file's status is a word git gives and no closed list: show one you
        do not know as modified. An omitted file shows its reason's message in
        place of its content; a reason's code is no closed list either.

        - The machine records the diff when a turn of one of the task's chats
        ends; each recording kept ticks the task.

        - Whoever reads the task reads its diff: a checkout's task is its
        person's alone, and another member of the organization finds no such
        task (404); a work tree Aether made is the organization's. A billing
        member is refused with 403 org_role_insufficient, a suspended
        organization with 403 org_suspended; 503 when the membership check is
        unavailable.
      operationId: getTaskDiff
      parameters:
        - in: path
          name: taskID
          required: true
          schema:
            format: uuid
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskDiff'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/TasksErrorResponse'
                  - $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Not Found
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Service Unavailable
components:
  schemas:
    TaskDiff:
      description: A task's recorded diff as its readers read it.
      discriminator:
        mapping:
          not_recorded: '#/components/schemas/TaskDiffNotRecorded'
          recorded: '#/components/schemas/TaskDiffRecorded'
        propertyName: state
      oneOf:
        - $ref: '#/components/schemas/TaskDiffRecorded'
        - $ref: '#/components/schemas/TaskDiffNotRecorded'
    TasksErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unserved
            - agent_pr_blocked
            - agent_pr_pending
            - agent_profile_changed
            - agent_starts_off
            - agent_uses_own_sign_in
            - answer_on_its_way
            - app_identity_missing
            - attachments_unsupported
            - attribution_unavailable
            - bad_gateway
            - bad_request
            - base_branch_unusable
            - branch_exists
            - caller_inactive
            - chat_archived
            - chat_being_forked
            - chat_moved
            - chat_not_removable
            - chat_settings_fixed
            - chats_not_addable
            - checkout_not_archivable
            - cli_upgrade_required
            - client_outdated
            - computer_cli_outdated
            - computer_starts_no_agents
            - computer_starts_no_forks
            - computer_unreachable
            - conflict
            - connection_creator_only
            - connection_harness_mismatch
            - connection_not_held
            - contents_write_required
            - continuation_failed
            - continuation_unavailable
            - control_forbidden
            - creator_github_access_missing
            - credential_kind_not_admitted
            - credential_named_file
            - detached_head
            - download_unsupported
            - embeddings_unavailable
            - feature_unsupported
            - file_references_unsupported
            - fix_not_requested
            - fix_requests_unrecorded
            - forbidden
            - fork_branch_delete_unsupported
            - fork_forbidden
            - fork_in_progress
            - fork_unsupported
            - gateway_timeout
            - github_claim_unverified
            - github_failed
            - github_identity_mismatch
            - github_identity_required
            - github_push_access_required
            - github_reconnect_required
            - github_ref_not_found
            - gone
            - handed_branch_protected
            - head_moved
            - html_render_nul_byte
            - html_render_too_large
            - idempotency_key_conflict
            - idempotency_key_reused
            - idle_compaction_not_pending
            - idle_compaction_skipped
            - inference_proxy_unavailable
            - insufficient_credits
            - insufficient_inference_balance
            - interaction_mode_unsupported
            - internal_error
            - invalid_request
            - last_queued_message
            - live_protocol_unsupported
            - main_chat_permanent
            - mcp_server_not_connected
            - merge_when_ready_requires_pr_review
            - message_not_queued
            - method_not_allowed
            - mode_forbidden
            - name_follows_session
            - no_checkout_on_computer
            - no_checkpoint_yet
            - no_commit
            - no_dispatch_target
            - no_main_chat
            - no_origin
            - no_turn_running
            - no_work_tree_folder
            - not_acceptable
            - not_found
            - not_implemented
            - onboarding_already_completed
            - onboarding_requirements_missing
            - open_in_terminal
            - org_id_required
            - org_role_insufficient
            - org_suspended
            - payment_required
            - pending_input_answered
            - permission_prompt_answered_in_terminal
            - permission_prompt_expired
            - permission_prompt_open
            - permission_prompt_stopped
            - pr_automation_unsupported
            - pr_review_actor_required
            - pr_review_connection_spent
            - pr_review_publish_forbidden
            - precondition_failed
            - project_archived
            - project_has_no_repository
            - project_repo_disconnected
            - project_repository_differs
            - project_required
            - pull_request_closed
            - pull_request_mirror_failed
            - pull_request_not_mirrored
            - push_failed
            - push_file_too_large
            - push_rejected
            - push_secret_detected
            - question_answers
            - question_shortened
            - queue_for_later_unsupported
            - queued_stop_requires_discard
            - rate_limited
            - reasoning_effort_fixed
            - repository_administration_not_granted
            - repository_already_connected
            - repository_create_forbidden
            - repository_create_rejected
            - repository_created_not_linked
            - repository_not_connected
            - repository_owner_not_caller
            - request_canceled
            - request_expired
            - request_timeout
            - request_too_large
            - review_name_follows_pull_request
            - sandbox_deleted
            - sandbox_failed
            - sandbox_needs_message
            - save_in_progress
            - save_requires_task_creator
            - service_unavailable
            - session_file_missing
            - session_gone
            - session_not_started_by_aether
            - slash_command
            - slash_commands_unsupported
            - stack_cycle
            - stack_too_large
            - stack_two_parents
            - stale_execution
            - stale_or_indeterminate
            - stale_pending_input
            - stream_delivery_gap
            - stream_event_conflict
            - task_already_saved
            - task_archived
            - task_awaiting_message
            - task_awaiting_tool_response
            - task_backed_by_work_tree
            - task_bound_at_creation
            - task_branch_diverged
            - task_branch_is_default
            - task_branch_mismatch
            - task_branch_missing
            - task_connection_disconnected
            - task_creator_deleted
            - task_executing
            - task_file_too_large
            - task_has_no_branch
            - task_has_no_commits
            - task_has_no_files
            - task_has_no_repository
            - task_history_has_merges
            - task_ineligible
            - task_is_child
            - task_not_accepting_messages
            - task_not_pinnable
            - task_not_started
            - task_rebase_in_progress
            - task_settings_changed
            - task_start_failed
            - task_start_pending
            - teleport_unavailable
            - terminal_chat
            - terminal_chat_continuation_refused
            - terminal_chat_run_running
            - terminal_question
            - too_large
            - too_many_live_connections
            - too_many_waiting_messages
            - turn_running
            - unauthenticated
            - unsigned_aether_head
            - unsigned_commit
            - unsupported_changes
            - unsupported_media_type
            - untyped_error
            - user_suspended
            - validation_failed
            - working_tree_dirty
            - workspace_git_unavailable
            - workspace_gone
            - workspace_outdated
            - workspace_rejected
            - workspace_start_failed
          minLength: 1
          type: string
        error:
          minLength: 1
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
      required:
        - error
        - code
      type: object
    OrgAuthorizationErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - org_membership_required
            - org_role_insufficient
            - org_suspended
            - account_deleting
            - agent_host_route_not_allowed
            - credential_kind_not_admitted
            - grant_scope_insufficient
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    TaskDiffNotRecorded:
      additionalProperties: false
      description: >-
        No diff of the task was ever recorded: every sandbox task's, and a task
        on a computer before its first recording.
      properties:
        last_failure:
          anyOf:
            - $ref: '#/components/schemas/TaskDiffFailure'
            - type: 'null'
          description: >-
            The latest attempt to record the diff, when it failed: newer than
            the recorded diff, or with none recorded. null otherwise. A failure
            never replaces a recorded diff.
        state:
          enum:
            - not_recorded
          type: string
      required:
        - state
        - last_failure
      type: object
    TaskDiffRecorded:
      additionalProperties: false
      description: The task's newest diff its computer's bridge recorded when a turn ended.
      properties:
        additions:
          description: The text files' added lines, summed.
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        base_branch:
          description: >-
            The branch on origin the diff is against, as
            getComputerWorkTreeDiffTarget names it.
          minLength: 1
          pattern: \S
          type: string
        base_ref:
          description: >-
            The merge base of HEAD and origin's base branch the diff runs from:
            a SHA-1 or SHA-256 commit.
          pattern: ^([0-9a-f]{40}|[0-9a-f]{64})$
          type: string
        deletions:
          description: The text files' deleted lines, summed.
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        files:
          description: >-
            Every file the work tree changed, at most 3000 whose paths take at
            most 1048576 bytes together (more is the failure too_many_files),
            each display_path once. Their hunks take at most 1048576 bytes as a
            unified diff writes them: the file whose hunks would pass that, and
            every file after it, is omitted too_large.
          items:
            $ref: '#/components/schemas/TaskDiffFile'
          maxItems: 3000
          type: array
        last_failure:
          anyOf:
            - $ref: '#/components/schemas/TaskDiffFailure'
            - type: 'null'
          description: >-
            The latest attempt to record the diff, when it failed: newer than
            the recorded diff, or with none recorded. null otherwise. A failure
            never replaces a recorded diff.
        recorded_at:
          description: When the computer's bridge observed the diff shown, on its clock.
          format: date-time
          type: string
        state:
          enum:
            - recorded
          type: string
      required:
        - state
        - recorded_at
        - base_branch
        - base_ref
        - additions
        - deletions
        - files
        - last_failure
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    TaskDiffFailure:
      additionalProperties: false
      description: >-
        The latest attempt to record the task's diff, which failed, and why:
        base_branch_gone, work_tree_gone, too_many_files, git_failed, or another
        a newer bridge names. Show the reason's message.
      properties:
        at:
          description: When the computer's bridge observed the failure, on its clock.
          format: date-time
          type: string
        reason:
          $ref: '#/components/schemas/TaskDiffReason'
      required:
        - at
        - reason
      type: object
    TaskDiffFile:
      description: >-
        A file the work tree changed against the merge base, staged, unstaged or
        untracked alike: text, with its hunks, or omitted, with why.
      discriminator:
        mapping:
          omitted: '#/components/schemas/TaskDiffOmittedFile'
          text: '#/components/schemas/TaskDiffTextFile'
        propertyName: kind
      oneOf:
        - $ref: '#/components/schemas/TaskDiffTextFile'
        - $ref: '#/components/schemas/TaskDiffOmittedFile'
    TaskDiffReason:
      additionalProperties: false
      properties:
        code:
          description: >-
            Why, as a word, and no closed list: an omitted file's binary,
            too_large or withheld; a failed recording's base_branch_gone,
            work_tree_gone, too_many_files or git_failed. A newer bridge may
            name another.
          maxLength: 64
          pattern: ^[a-z][a-z0-9_]*$
          type: string
        message:
          description: >-
            A sentence for a person. The API writes its own for every code it
            knows, whatever the bridge sent.
          maxLength: 1000
          minLength: 1
          pattern: \S
          type: string
      required:
        - code
        - message
      type: object
    TaskDiffOmittedFile:
      additionalProperties: false
      description: >-
        A file listed without its content, for its reason: binary, the file is
        binary; too_large, the diff's hunks pass the bound with this file's;
        withheld, its name is a credential file's, or a line of a hunk, either
        side or context, holds a token of a credential's format. Show the
        reason's message in place of the content.
      properties:
        display_path:
          description: new_path, or old_path for a deleted file.
          maxLength: 4096
          minLength: 1
          type: string
        kind:
          enum:
            - omitted
          type: string
        new_path:
          description: The file's path on disk; null for a deleted file.
          maxLength: 4096
          minLength: 1
          type:
            - string
            - 'null'
        old_path:
          description: The file's path in the merge base; null for an added file.
          maxLength: 4096
          minLength: 1
          type:
            - string
            - 'null'
        reason:
          $ref: '#/components/schemas/TaskDiffReason'
        status:
          description: >-
            How the file changed, a word git gives: added, modified, deleted or
            renamed, and no closed list.
          maxLength: 32
          pattern: ^[a-z][a-z0-9_]*$
          type: string
      required:
        - kind
        - status
        - old_path
        - new_path
        - display_path
        - reason
      type: object
    TaskDiffTextFile:
      additionalProperties: false
      description: A text file with its hunks.
      properties:
        additions:
          description: Its hunks' added lines.
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        deletions:
          description: Its hunks' deleted lines.
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        display_path:
          description: new_path, or old_path for a deleted file.
          maxLength: 4096
          minLength: 1
          type: string
        hunks:
          description: Its hunks; none for a rename alone or a mode change.
          items:
            $ref: '#/components/schemas/GitDiffHunk'
          type: array
        kind:
          enum:
            - text
          type: string
        new_path:
          description: The file's path on disk; null for a deleted file.
          maxLength: 4096
          minLength: 1
          type:
            - string
            - 'null'
        old_path:
          description: The file's path in the merge base; null for an added file.
          maxLength: 4096
          minLength: 1
          type:
            - string
            - 'null'
        status:
          description: >-
            How the file changed, a word git gives: added, modified, deleted or
            renamed, and no closed list.
          maxLength: 32
          pattern: ^[a-z][a-z0-9_]*$
          type: string
      required:
        - kind
        - status
        - old_path
        - new_path
        - display_path
        - additions
        - deletions
        - hunks
      type: object
    GitDiffHunk:
      additionalProperties: false
      description: A hunk of a file's unified diff, as the sandbox's live diff shows one.
      properties:
        header:
          description: >-
            The hunk's @@ -old_start,old_count +new_start,new_count @@ line, as
            git writes it.
          minLength: 1
          type: string
        lines:
          description: >-
            The hunk's lines, numbered from its starts: each side's lines are
            its count.
          items:
            discriminator:
              mapping:
                add: '#/components/schemas/GitDiffAddLine'
                context: '#/components/schemas/GitDiffContextLine'
                del: '#/components/schemas/GitDiffDelLine'
              propertyName: kind
            oneOf:
              - $ref: '#/components/schemas/GitDiffAddLine'
              - $ref: '#/components/schemas/GitDiffDelLine'
              - $ref: '#/components/schemas/GitDiffContextLine'
          type: array
        new_count:
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        new_start:
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        old_count:
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        old_start:
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
      required:
        - header
        - old_start
        - old_count
        - new_start
        - new_count
        - lines
      type: object
    GitDiffAddLine:
      additionalProperties: false
      description: A line the file adds.
      properties:
        kind:
          enum:
            - add
          type: string
        new_line:
          description: Its line in the new file.
          format: int64
          maximum: 9007199254740991
          minimum: 1
          type: integer
        no_trailing_newline:
          description: true when the line ends its side of the file with no newline.
          type: boolean
        old_line:
          type: 'null'
        text:
          description: The line, without its +, - or space and without its newline.
          type: string
      required:
        - kind
        - old_line
        - new_line
        - text
      type: object
    GitDiffContextLine:
      additionalProperties: false
      description: A line both sides hold.
      properties:
        kind:
          enum:
            - context
          type: string
        new_line:
          description: Its line in the new file.
          format: int64
          maximum: 9007199254740991
          minimum: 1
          type: integer
        no_trailing_newline:
          description: true when the line ends its side of the file with no newline.
          type: boolean
        old_line:
          description: Its line in the old file.
          format: int64
          maximum: 9007199254740991
          minimum: 1
          type: integer
        text:
          description: The line, without its +, - or space and without its newline.
          type: string
      required:
        - kind
        - old_line
        - new_line
        - text
      type: object
    GitDiffDelLine:
      additionalProperties: false
      description: A line the file deletes.
      properties:
        kind:
          enum:
            - del
          type: string
        new_line:
          type: 'null'
        no_trailing_newline:
          description: true when the line ends its side of the file with no newline.
          type: boolean
        old_line:
          description: Its line in the old file.
          format: int64
          maximum: 9007199254740991
          minimum: 1
          type: integer
        text:
          description: The line, without its +, - or space and without its newline.
          type: string
      required:
        - kind
        - old_line
        - new_line
        - text
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

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