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

# List the tasks a computer is to start

> Lists the starts the caller's machine bridge has not carried out, the oldest first: each a task started on the computer whose work tree the bridge has not made (pending), or whose first message's run it has not asked for (prepared).

Use this tool when you need to:
- Make the work trees of the tasks started on the computer while the bridge was not connected, whose start_task command expired
- Learn, after the bridge restarted, which starts it left unfinished
- Find the work tree a run's session starts in, when Claude Code holds no file of the session yet: the session of a task started on the computer exists only once its first run starts it

Examples:
- GET /computers/{computerID}/task-starts
- GET /computers/{computerID}/task-starts?session_id=8a1f2c3d-4b5e-4f60-8a7b-9c0d1e2f3a4b

Hints:
- Without session_id, lists none while the computer does not let Aether start agents: a start waits until the computer turns that on.
- With session_id, lists the start whose task's main chat is that session, in whatever state, or none: start the session in a prepared start's folder, under the session's id.
- A start Aether ended (its task was archived, it waited 24 hours from when it was written, or the sign-in or API key it was made with ended) is never listed, and getComputerTaskStart answers it 404 not_found.
- Make each pending start's work tree and report it with reportComputerTaskStart; ask to run each prepared start's first message (first_message_id) with reportTerminalChatRun.
- A computer that is not the caller's is refused with 404 not_found.
- Only the grant of the caller's coding agent's bridge calls it, the machine bridge on the computer: a session or an API key is refused with 403 credential_kind_not_admitted.
- The call presents the computer's own secret, which aether setup keeps on it, in the Aether-Computer-Secret header. A computer that has none is refused with 403 computer_needs_setup: update the aether CLI there and run aether setup. A call that presents no secret, or another, is refused with 403 computer_set_up_elsewhere.



## OpenAPI

````yaml api-reference/openapi.json GET /computers/{computerID}/task-starts
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /computers/{computerID}/task-starts:
    get:
      tags:
        - computers
      summary: List the tasks a computer is to start
      description: >-
        Lists the starts the caller's machine bridge has not carried out, the
        oldest first: each a task started on the computer whose work tree the
        bridge has not made (pending), or whose first message's run it has not
        asked for (prepared).


        Use this tool when you need to:

        - Make the work trees of the tasks started on the computer while the
        bridge was not connected, whose start_task command expired

        - Learn, after the bridge restarted, which starts it left unfinished

        - Find the work tree a run's session starts in, when Claude Code holds
        no file of the session yet: the session of a task started on the
        computer exists only once its first run starts it


        Examples:

        - GET /computers/{computerID}/task-starts

        - GET
        /computers/{computerID}/task-starts?session_id=8a1f2c3d-4b5e-4f60-8a7b-9c0d1e2f3a4b


        Hints:

        - Without session_id, lists none while the computer does not let Aether
        start agents: a start waits until the computer turns that on.

        - With session_id, lists the start whose task's main chat is that
        session, in whatever state, or none: start the session in a prepared
        start's folder, under the session's id.

        - A start Aether ended (its task was archived, it waited 24 hours from
        when it was written, or the sign-in or API key it was made with ended)
        is never listed, and getComputerTaskStart answers it 404 not_found.

        - Make each pending start's work tree and report it with
        reportComputerTaskStart; ask to run each prepared start's first message
        (first_message_id) with reportTerminalChatRun.

        - A computer that is not the caller's is refused with 404 not_found.

        - Only the grant of the caller's coding agent's bridge calls it, the
        machine bridge on the computer: a session or an API key is refused with
        403 credential_kind_not_admitted.

        - The call presents the computer's own secret, which aether setup keeps
        on it, in the Aether-Computer-Secret header. A computer that has none is
        refused with 403 computer_needs_setup: update the aether CLI there and
        run aether setup. A call that presents no secret, or another, is refused
        with 403 computer_set_up_elsewhere.
      operationId: listComputerTaskStarts
      parameters:
        - in: path
          name: computerID
          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
        - description: >-
            Claude Code's id of a session: lists the start whose task's main
            chat it is, whatever it stands at, if there is one.
          explode: false
          in: query
          name: session_id
          schema:
            description: >-
              Claude Code's id of a session: lists the start whose task's main
              chat it is, whatever it stands at, if there is one.
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputerTaskStartList'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ComputersErrorResponse'
                  - $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Not Found
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Internal Server Error
components:
  schemas:
    ComputerTaskStartList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/ComputerTaskStart'
          type: array
      required:
        - items
      type: object
    ComputersErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unserved
            - agent_pr_blocked
            - agent_pr_pending
            - agent_profile_changed
            - agent_starts_off
            - agent_starts_on_from_computer_only
            - 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_needs_fresh_sign_in
            - computer_needs_setup
            - computer_registered_to_another_person
            - computer_set_up_elsewhere
            - computer_starts_no_agents
            - computer_starts_no_forks
            - computer_task_start_moved
            - computer_unreachable
            - conflict
            - connection_creator_only
            - connection_harness_mismatch
            - connection_not_held
            - contents_write_required
            - continuation_failed
            - continuation_unavailable
            - control_forbidden
            - 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_failed
            - github_identity_required
            - github_push_access_required
            - 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
            - message_not_waiting
            - 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_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_open
            - pr_automation_unsupported
            - pr_review_actor_required
            - pr_review_connection_spent
            - pr_review_publish_forbidden
            - precondition_failed
            - project_has_no_repository
            - project_not_a_choice
            - project_required
            - prompt_decisions_refused
            - pull_request_closed
            - pull_request_mirror_failed
            - pull_request_not_mirrored
            - push_failed
            - question_answers
            - question_shortened
            - queue_for_later_unsupported
            - queued_stop_requires_discard
            - rate_limited
            - reasoning_effort_fixed
            - remote_changes_on_from_computer_only
            - repository_not_connected
            - request_canceled
            - request_expired
            - request_timeout
            - request_too_large
            - review_name_follows_pull_request
            - sandbox_deleted
            - sandbox_failed
            - sandbox_needs_message
            - service_unavailable
            - session_file_generation
            - session_file_hole
            - session_file_missing
            - session_file_range_differs
            - session_gone
            - session_not_started_by_aether
            - slash_commands_unsupported
            - stack_cycle
            - stack_too_large
            - stack_two_parents
            - stale_execution
            - stale_or_indeterminate
            - stale_pending_input
            - start_cancelled
            - stream_delivery_gap
            - stream_event_conflict
            - task_archived
            - task_awaiting_message
            - task_awaiting_tool_response
            - task_backed_by_work_tree
            - task_connection_disconnected
            - task_creator_deleted
            - task_has_no_branch
            - task_has_no_repository
            - task_ineligible
            - task_not_accepting_messages
            - task_not_pinnable
            - task_not_started
            - task_settings_changed
            - task_start_failed
            - task_start_pending
            - teleport_unavailable
            - terminal_chat
            - terminal_chat_continuation_refused
            - terminal_chat_prompt_closed_otherwise
            - terminal_chat_prompt_differs
            - terminal_chat_prompt_not_answered
            - terminal_chat_removed
            - terminal_chat_run_moved
            - 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
            - work_tree_repository_differs
            - 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
    ComputerTaskStart:
      description: >-
        A task started on the computer, as its machine bridge carries it out:
        the work tree to make, the session the task's main chat is, and where
        the start stands.
      discriminator:
        mapping:
          failed: '#/components/schemas/ComputerTaskStartFailed'
          pending: '#/components/schemas/ComputerTaskStartPending'
          prepared: '#/components/schemas/ComputerTaskStartPrepared'
        propertyName: state
      oneOf:
        - $ref: '#/components/schemas/ComputerTaskStartPending'
        - $ref: '#/components/schemas/ComputerTaskStartPrepared'
        - $ref: '#/components/schemas/ComputerTaskStartFailed'
    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
    ComputerTaskStartFailed:
      additionalProperties: false
      description: >-
        The bridge could not make the work tree: checkout_missing,
        base_branch_unreachable or work_tree_failed; or, for a fork, could not
        place its session files: session_unplaced.
      properties:
        agent:
          description: >-
            The catalog type of the agent the task's main chat runs, such as
            claude-code. Always sent.
          minLength: 1
          type: string
        base_branch:
          description: >-
            The branch on the checkout's origin the task's branch starts from,
            and its pull request goes to.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        branch:
          description: >-
            The task's own branch, which the work tree is made on: a new task's
            is cut from base_branch on origin, a fork's is on origin already,
            pushed with the source's work.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        checkout:
          description: >-
            The person's checkout of the repository on the computer the work
            tree is added from.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        folder:
          description: The folder the work tree is made at.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        fork:
          anyOf:
            - $ref: '#/components/schemas/ComputerTaskStartFork'
            - type: 'null'
          description: >-
            The session the main chat's first run forks, for a task forked to
            the computer from another chat; null for a new task.
        id:
          description: The start's id, its start_task command's.
          format: uuid
          type: string
        prompt:
          description: The task's prompt, the main chat's first message.
          maxLength: 65536
          minLength: 1
          type: string
        reason:
          enum:
            - checkout_missing
            - base_branch_unreachable
            - work_tree_failed
            - session_unplaced
          type: string
        repository:
          $ref: '#/components/schemas/ComputerTaskStartRepository'
        session_id:
          description: >-
            The id Claude Code's session takes when the task's first run starts
            it: the task's main chat.
          format: uuid
          type: string
        state:
          enum:
            - failed
          type: string
        task_id:
          description: The task the start is of.
          format: uuid
          type: string
      required:
        - id
        - task_id
        - session_id
        - repository
        - checkout
        - folder
        - branch
        - base_branch
        - prompt
        - fork
        - state
        - reason
      type: object
    ComputerTaskStartPending:
      additionalProperties: false
      description: >-
        The bridge has not made the work tree: make it, then report it with
        reportComputerTaskStart.
      properties:
        agent:
          description: >-
            The catalog type of the agent the task's main chat runs, such as
            claude-code. Always sent.
          minLength: 1
          type: string
        base_branch:
          description: >-
            The branch on the checkout's origin the task's branch starts from,
            and its pull request goes to.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        branch:
          description: >-
            The task's own branch, which the work tree is made on: a new task's
            is cut from base_branch on origin, a fork's is on origin already,
            pushed with the source's work.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        checkout:
          description: >-
            The person's checkout of the repository on the computer the work
            tree is added from.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        folder:
          description: The folder the work tree is made at.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        fork:
          anyOf:
            - $ref: '#/components/schemas/ComputerTaskStartFork'
            - type: 'null'
          description: >-
            The session the main chat's first run forks, for a task forked to
            the computer from another chat; null for a new task.
        id:
          description: The start's id, its start_task command's.
          format: uuid
          type: string
        prompt:
          description: The task's prompt, the main chat's first message.
          maxLength: 65536
          minLength: 1
          type: string
        repository:
          $ref: '#/components/schemas/ComputerTaskStartRepository'
        session_id:
          description: >-
            The id Claude Code's session takes when the task's first run starts
            it: the task's main chat.
          format: uuid
          type: string
        state:
          enum:
            - pending
          type: string
        task_id:
          description: The task the start is of.
          format: uuid
          type: string
      required:
        - id
        - task_id
        - session_id
        - repository
        - checkout
        - folder
        - branch
        - base_branch
        - prompt
        - fork
        - state
      type: object
    ComputerTaskStartPrepared:
      additionalProperties: false
      description: >-
        The bridge made the work tree, and the prompt is the main chat's first
        message, which waits on the computer: ask to run it with
        reportTerminalChatRun, starting the session in the folder under
        session_id.
      properties:
        agent:
          description: >-
            The catalog type of the agent the task's main chat runs, such as
            claude-code. Always sent.
          minLength: 1
          type: string
        base_branch:
          description: >-
            The branch on the checkout's origin the task's branch starts from,
            and its pull request goes to.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        branch:
          description: >-
            The task's own branch, which the work tree is made on: a new task's
            is cut from base_branch on origin, a fork's is on origin already,
            pushed with the source's work.
          maxLength: 255
          minLength: 1
          pattern: "^[^-\\0- \\x7f-\\xa0  - \L\P  　][^\\0- \\x7f-\\xa0  - \L\P  　]*$"
          type: string
          x-aether-string-length-unit: unicode-code-point
        checkout:
          description: >-
            The person's checkout of the repository on the computer the work
            tree is added from.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        first_message_id:
          description: >-
            The main chat's first message, the prompt: the message its first run
            runs with.
          format: uuid
          type: string
        folder:
          description: The folder the work tree is made at.
          maxLength: 4096
          minLength: 1
          pattern: ^/
          type: string
          x-aether-string-length-unit: unicode-code-point
        fork:
          anyOf:
            - $ref: '#/components/schemas/ComputerTaskStartFork'
            - type: 'null'
          description: >-
            The session the main chat's first run forks, for a task forked to
            the computer from another chat; null for a new task.
        id:
          description: The start's id, its start_task command's.
          format: uuid
          type: string
        prompt:
          description: The task's prompt, the main chat's first message.
          maxLength: 65536
          minLength: 1
          type: string
        repository:
          $ref: '#/components/schemas/ComputerTaskStartRepository'
        session_id:
          description: >-
            The id Claude Code's session takes when the task's first run starts
            it: the task's main chat.
          format: uuid
          type: string
        state:
          enum:
            - prepared
          type: string
        task_id:
          description: The task the start is of.
          format: uuid
          type: string
      required:
        - id
        - task_id
        - session_id
        - repository
        - checkout
        - folder
        - branch
        - base_branch
        - prompt
        - fork
        - state
        - first_message_id
      type: object
    ComputerTaskStartFork:
      additionalProperties: false
      description: >-
        A task forked to the computer from another chat: the session its first
        run forks, and the files the bridge places for it before it reports the
        start prepared.
      properties:
        session_id:
          description: >-
            The source's Claude Code session: place its file,
            getComputerTaskStartFile session, as <session_id>.jsonl in the
            Claude Code projects folder of the work tree's resolved folder, and
            the first run forks it with claude -p --resume <session_id>
            --fork-session --session-id <the start's session_id>.
          format: uuid
          type: string
        subagents:
          description: >-
            The source session's sub-agent files, each placed as
            <session_id>/subagents/<name>.jsonl; empty for a cloud chat's
            session.
          items:
            description: >-
              agent-<id>, a sub-agent's file Claude Code writes beside its
              session's under <session>/subagents/.
            pattern: ^agent-[A-Za-z0-9_-]{1,64}$
            type: string
          type: array
      required:
        - session_id
        - subagents
      type: object
    ComputerTaskStartRepository:
      additionalProperties: false
      properties:
        name:
          minLength: 1
          type: string
        owner:
          minLength: 1
          type: string
      required:
        - owner
        - name
      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.