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

# Get your agent

> Reads the caller's personal agent: its state, settings and models, what it runs on, its default project, its daily spend cap with what it spent today and this month, the balance that pays for it, and what it takes next.

Use this tool when you need to:
- Check whether the caller has a personal agent and what state it is in (running, asleep, paused, resuming)
- See what the agent runs on and on which model, its daily spend cap, and what it spent today and this month
- Find the message the agent takes next, or the edit of its memory it applies next

Examples:
- GET /agent

Hints:
- Takes no parameters. state is the agent's lifecycle state: running; suspending and idle, asleep and woken by the next message; waking and resuming, coming up; provisioning and booting, being created; updating, moving onto a new image; pausing and paused, backed up; lost, its machine gone; destroying, being deleted.
- runs_on is aether (Aether inference) or stored with the connection's id, option and name; model is what the agent converses on and cron_model what its scheduled jobs run on unless a job names another (Claude Haiku 5.5 or GPT-6 Luna, from the model's family); default_project_id is the project's id, null while it has none; browser_tools is whether it may drive a browser.
- daily_cap_microdollars is its daily spend cap; usage_today and usage_this_month are what it spent, the day and the month in the caller's timezone (timezone); balance is the caller's personal organization's Aether inference balance, which pays for it, with exhausted once it is used up.
- pending_message_id is the message it takes next (listAgentMessages) and pending_memory_edit_id the edit of its memory it applies next (getAgentMemoryEdit), each null when none is pending.
- Use getAgentMemory instead for its memory, listAgentToolUsage for its tool calls this month, getAgentPhone for the caller's phone link, and patchAgent to change the agent.
- Any signed-in user, for their own agent alone, the agent host's grant included; refused with 404 agent_not_found until they have one.



## OpenAPI

````yaml api-reference/openapi.json GET /agent
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /agent:
    get:
      tags:
        - agent
      summary: Get your agent
      description: >-
        Reads the caller's personal agent: its state, settings and models, what
        it runs on, its default project, its daily spend cap with what it spent
        today and this month, the balance that pays for it, and what it takes
        next.


        Use this tool when you need to:

        - Check whether the caller has a personal agent and what state it is in
        (running, asleep, paused, resuming)

        - See what the agent runs on and on which model, its daily spend cap,
        and what it spent today and this month

        - Find the message the agent takes next, or the edit of its memory it
        applies next


        Examples:

        - GET /agent


        Hints:

        - Takes no parameters. state is the agent's lifecycle state: running;
        suspending and idle, asleep and woken by the next message; waking and
        resuming, coming up; provisioning and booting, being created; updating,
        moving onto a new image; pausing and paused, backed up; lost, its
        machine gone; destroying, being deleted.

        - runs_on is aether (Aether inference) or stored with the connection's
        id, option and name; model is what the agent converses on and cron_model
        what its scheduled jobs run on unless a job names another (Claude Haiku
        5.5 or GPT-6 Luna, from the model's family); default_project_id is the
        project's id, null while it has none; browser_tools is whether it may
        drive a browser.

        - daily_cap_microdollars is its daily spend cap; usage_today and
        usage_this_month are what it spent, the day and the month in the
        caller's timezone (timezone); balance is the caller's personal
        organization's Aether inference balance, which pays for it, with
        exhausted once it is used up.

        - pending_message_id is the message it takes next (listAgentMessages)
        and pending_memory_edit_id the edit of its memory it applies next
        (getAgentMemoryEdit), each null when none is pending.

        - Use getAgentMemory instead for its memory, listAgentToolUsage for its
        tool calls this month, getAgentPhone for the caller's phone link, and
        patchAgent to change the agent.

        - Any signed-in user, for their own agent alone, the agent host's grant
        included; refused with 404 agent_not_found until they have one.
      operationId: getAgent
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentErrorResponse'
          description: Internal Server Error
components:
  schemas:
    Agent:
      additionalProperties: false
      properties:
        balance:
          $ref: '#/components/schemas/AgentBalance'
        browser_tools:
          description: >-
            Whether your agent may drive a browser. Off by default; a change
            applies when Hermes next starts, which a running agent does at once.
          type: boolean
        created_at:
          format: date-time
          type: string
        cron_model:
          description: >-
            The model your agent's scheduled jobs run on, unless a job names
            another.
          enum:
            - claude-fable-5-1
            - claude-opus-5-5
            - claude-sonnet-5-5
            - claude-haiku-5-5
            - gpt-6.1-sol
            - gpt-6-sol
            - gpt-6-astra
            - gpt-6-luna
          type: string
        daily_cap_microdollars:
          description: >-
            The most your agent may spend from your balance in a day, over every
            model call it makes on Aether inference and every tool call while
            tool calls are charged, in millionths of a US dollar, a whole number
            of cents. Such a call is refused (402 agent_host_daily_cap_reached)
            once the day's settled spend plus what the agent's calls in flight
            hold reaches it, until midnight in your timezone, until calls in
            flight settle under it, or until the cap is raised past them.
          format: int64
          type: integer
        default_project_id:
          description: >-
            The project a task your agent starts runs on when it names no
            repository; null while it has none, when such a task is refused.
          format: uuid
          type:
            - string
            - 'null'
        id:
          format: uuid
          type: string
        last_used_at:
          description: >-
            When your agent was created or resumed, was sent a message, or last
            worked. Thirty days unused pauses it.
          format: date-time
          type: string
        model:
          description: The model your agent converses on.
          enum:
            - claude-fable-5-1
            - claude-opus-5-5
            - claude-sonnet-5-5
            - claude-haiku-5-5
            - gpt-6.1-sol
            - gpt-6-sol
            - gpt-6-astra
            - gpt-6-luna
          type: string
        pending_memory_edit_id:
          description: >-
            The edit of its memory your agent applies next (getAgentMemoryEdit),
            wherever it was made, including one whose wake timed out after it
            was queued; null when none is pending.
          format: uuid
          type:
            - string
            - 'null'
        pending_message_id:
          description: >-
            The message your agent takes next, wherever it falls in your thread
            (listAgentMessages); null when none is pending.
          format: uuid
          type:
            - string
            - 'null'
        runs_on:
          $ref: '#/components/schemas/AgentRunsOn'
        state:
          description: >-
            The host's lifecycle state. running: Hermes takes messages now;
            suspending and idle: asleep, woken by the next message; waking,
            resuming: coming up for a message; provisioning and booting: being
            created; updating: moving onto a new image; pausing and paused:
            backed up after thirty days unused, or paused by you, and resumed by
            you (a message from the web does not resume it); lost: its machine
            is gone and only deleting it helps; destroying: being deleted.
          enum:
            - provisioning
            - booting
            - running
            - suspending
            - idle
            - waking
            - updating
            - pausing
            - paused
            - resuming
            - lost
            - destroying
            - destroyed
          type: string
        timezone:
          description: Your IANA timezone, in which the agent's days and months begin.
          type: string
        usage_this_month:
          $ref: '#/components/schemas/AgentUsage'
        usage_today:
          $ref: '#/components/schemas/AgentDayUsage'
      required:
        - id
        - state
        - default_project_id
        - browser_tools
        - runs_on
        - model
        - cron_model
        - daily_cap_microdollars
        - last_used_at
        - created_at
        - timezone
        - usage_this_month
        - usage_today
        - balance
        - pending_message_id
        - pending_memory_edit_id
      type: object
    AgentErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unavailable
            - aether_inference_unserved
            - agent_connector_not_found
            - agent_credential_unreadable
            - agent_default_project_archived
            - agent_event_not_found
            - agent_host_account_deleting
            - agent_host_command_not_found
            - agent_host_creation_disabled
            - agent_host_exists
            - agent_host_illegal_transition
            - agent_host_not_allowlisted
            - agent_host_not_found
            - agent_host_not_ready
            - agent_host_other_provider_app
            - agent_host_project_not_eligible
            - agent_host_provisioning_failed
            - agent_host_state_changed
            - agent_host_wake_failed
            - agent_line_unavailable
            - agent_link_code_picked_up
            - agent_link_expired
            - agent_link_invalid_code
            - agent_link_needs_web_session
            - agent_link_no_verified_phone
            - agent_link_not_found
            - agent_link_other_account
            - agent_link_takes_a_code
            - agent_link_takes_no_code
            - agent_link_used
            - agent_memory_edit_not_found
            - agent_memory_not_reported
            - agent_message_not_found
            - agent_message_pending
            - agent_not_found
            - agent_profile_changed
            - agent_profile_harness_fixed
            - bad_gateway
            - bad_request
            - conflict
            - connection_account_held
            - connection_agent_only
            - connection_harness_mismatch
            - connection_is_default
            - connection_kind_not_runnable
            - connection_name_taken
            - connection_not_found
            - connection_not_held
            - connection_not_of_agent_family
            - connection_option_mismatch
            - connection_runs_agent
            - connection_runs_profiles
            - control_forbidden
            - creator_github_access_missing
            - default_skill_required
            - device_auth_not_found
            - fallback_is_own_connection
            - fallback_required_with_pin
            - fallback_requires_pin
            - forbidden
            - gateway_timeout
            - github_auth_check_unavailable
            - github_claim_unverified
            - github_identity_mismatch
            - github_reconnect_required
            - github_ref_not_found
            - gone
            - integration_auth_unexpected
            - integration_not_in_directory
            - integration_shape_changed
            - internal_error
            - line_exists
            - line_not_found
            - line_not_imessage
            - mcp_connection_github_not_connected
            - mcp_connection_oauth_not_accepted
            - mcp_connection_org_not_offered
            - mcp_connection_secret_invalid
            - mcp_connection_server_changed
            - mcp_connection_static_secret_not_accepted
            - mcp_credential_policy_not_applicable
            - mcp_credential_policy_org_unavailable
            - mcp_credential_policy_required
            - mcp_oauth_app_auth_method_unsupported
            - mcp_oauth_app_invalid
            - mcp_oauth_app_issuer_invalid
            - mcp_oauth_app_required
            - mcp_oauth_not_advertised
            - mcp_oauth_pkce_unsupported
            - mcp_oauth_registration_failed
            - mcp_repo_config_invalid
            - mcp_server_address_refused
            - mcp_server_aether_managed
            - mcp_server_api_key_not_applicable
            - mcp_server_args_invalid
            - mcp_server_auth_discovery_failed
            - mcp_server_auth_unsupported
            - mcp_server_directory_managed
            - mcp_server_directory_moved
            - mcp_server_display_name_invalid
            - mcp_server_env_invalid
            - mcp_server_headers_invalid
            - mcp_server_key_invalid
            - mcp_server_key_reserved
            - mcp_server_key_taken
            - mcp_server_kind_change_refused
            - mcp_server_not_from_directory
            - mcp_server_not_mcp
            - mcp_server_package_invalid
            - mcp_server_plugin_bundled
            - mcp_server_plugin_off
            - mcp_server_response_too_large
            - mcp_server_return_to_invalid
            - mcp_server_runtime_invalid
            - mcp_server_switched_off
            - mcp_server_unreachable
            - mcp_server_url_invalid
            - mcp_server_version_unpinned
            - method_not_allowed
            - model_not_on_aether_inference
            - no_default_connection
            - no_dispatch_target
            - not_acceptable
            - not_an_agent_host
            - not_found
            - not_implemented
            - org_role_insufficient
            - org_suspended
            - payment_required
            - plugin_moved
            - plugin_name_taken
            - plugin_request_invalid
            - plugin_server_key_reserved
            - plugin_server_key_taken
            - plugin_server_probe_failed
            - plugin_server_required
            - plugin_skill_invalid
            - plugin_source_address_refused
            - plugin_source_empty
            - plugin_source_invalid
            - plugin_source_not_found
            - plugin_source_not_public
            - plugin_source_too_large
            - plugin_source_unreachable
            - plugin_source_unsupported
            - plugin_switched_off
            - plugin_undeliverable
            - precondition_failed
            - project_archived
            - project_has_no_repository
            - project_repo_disconnected
            - project_repository_differs
            - push_file_too_large
            - push_rejected
            - push_secret_detected
            - rate_limited
            - repository_administration_not_granted
            - repository_already_connected
            - repository_create_forbidden
            - repository_create_rejected
            - repository_created_not_linked
            - repository_not_reachable
            - repository_owner_not_caller
            - request_canceled
            - request_timeout
            - request_too_large
            - save_in_progress
            - save_requires_task_creator
            - service_unavailable
            - skill_slug_reserved
            - task_already_saved
            - task_backed_by_work_tree
            - task_bound_at_creation
            - task_branch_diverged
            - task_branch_is_default
            - task_branch_mismatch
            - task_branch_missing
            - task_creator_deleted
            - task_executing
            - task_file_too_large
            - task_has_no_commits
            - task_has_no_files
            - task_history_has_merges
            - task_is_child
            - task_not_started
            - task_rebase_in_progress
            - unauthenticated
            - unsupported_media_type
            - validation_failed
            - whatsapp_not_enabled
            - working_tree_dirty
            - workspace_gone
            - workspace_outdated
          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
    AgentBalance:
      additionalProperties: false
      properties:
        exhausted:
          description: >-
            Whether the balance is used up: your agent's model calls are refused
            until you add funds.
          type: boolean
        microdollars:
          description: >-
            Your personal organization's Aether inference balance, in millionths
            of a US dollar; your agent's model calls are paid from it.
          format: int64
          type: integer
      required:
        - microdollars
        - exhausted
      type: object
    AgentRunsOn:
      discriminator:
        mapping:
          aether: '#/components/schemas/AgentRunsOnAether'
          stored: '#/components/schemas/AgentRunsOnStored'
        propertyName: runs_on
      oneOf:
        - $ref: '#/components/schemas/AgentRunsOnAether'
        - $ref: '#/components/schemas/AgentRunsOnStored'
    AgentUsage:
      additionalProperties: false
      properties:
        month:
          description: This month in your timezone, as YYYY-MM.
          pattern: ^[0-9]{4}-[0-9]{2}$
          type: string
        spent_microdollars:
          description: >-
            What your agent's model calls, and its tool calls while they are
            charged, settled this month, in millionths of a US dollar, from your
            balance.
          format: int64
          type: integer
      required:
        - month
        - spent_microdollars
      type: object
    AgentDayUsage:
      additionalProperties: false
      properties:
        day:
          description: >-
            Today in the agent's timezone, as YYYY-MM-DD; the next day starts at
            its midnight.
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
          type: string
        spent_microdollars:
          description: >-
            What the agent's model calls on Aether inference, and its tool calls
            while they are charged, settled today, in millionths of a US dollar:
            what the daily cap holds to.
          format: int64
          type: integer
      required:
        - day
        - spent_microdollars
      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
    AgentRunsOnAether:
      additionalProperties: false
      properties:
        runs_on:
          description: >-
            Aether inference, paid from the owner's balance and held to the
            daily cap.
          enum:
            - aether
          type: string
      required:
        - runs_on
      type: object
    AgentRunsOnStored:
      additionalProperties: false
      properties:
        id:
          format: uuid
          type: string
        name:
          minLength: 1
          type: string
        option:
          enum:
            - claude_plan
            - anthropic_api_key
            - openai_api_key
          type: string
        runs_on:
          description: >-
            The owner's connection, paid by its plan or key, neither from the
            balance nor held to the cap.
          enum:
            - stored
          type: string
      required:
        - runs_on
        - id
        - option
        - 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.