> ## 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 > Your personal agent: its state, settings and models, what it spent this month and its daily spend cap, in your timezone, its calls this month to each tool provider, the balance that pays for it, your personal organization's Aether inference balance, and what it thinks on. 404 agent_not_found until you have one; 409 agent_credential_unreadable while the connection it runs on cannot be read; reconnect it in Settings › Connections. ## 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: >- Your personal agent: its state, settings and models, what it spent this month and its daily spend cap, in your timezone, its calls this month to each tool provider, the balance that pays for it, your personal organization's Aether inference balance, and what it thinks on. 404 agent_not_found until you have one; 409 agent_credential_unreadable while the connection it runs on cannot be read; reconnect it in Settings › Connections. operationId: getAgent responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentRead' 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 '409': content: application/json: schema: $ref: '#/components/schemas/AgentErrorResponse' description: Conflict '500': content: application/json: schema: $ref: '#/components/schemas/AgentErrorResponse' description: Internal Server Error components: schemas: AgentRead: 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 connection_id: description: >- The connection your agent runs on; present exactly when runs_on is stored. format: uuid type: string 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: $ref: '#/components/schemas/AgentDailyCap' default_project_id: description: >- The project a task your agent starts runs on when it names no repository. Without it such a task is refused. format: uuid type: string 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 memory: $ref: '#/components/schemas/AgentMemory' memory_edit: $ref: '#/components/schemas/AgentMemoryEdit' 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 runs_on: description: >- What your agent runs on: aether, Aether inference, paid from your balance and held to the daily cap; stored, your connection connection_id names, paid by its plan or key, neither from your balance nor held to the cap. enum: - aether - stored type: string 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 thinks_on: description: >- What your agent thinks on, from the kind of the connection it runs on: aether, Aether inference, paid from your balance and held to the daily cap; claude_plan, your Claude plan through its setup token; claude_api_key, Anthropic's API on your Anthropic API key; openai_api_key, OpenAI's API on your OpenAI API key. None of the last three is paid from your balance or held to the daily cap. enum: - aether - claude_plan - claude_api_key - openai_api_key type: string timezone: description: Your IANA timezone, in which the agent's days and months begin. type: string tool_usage: description: >- Your agent's calls this month to each tool provider Aether pays for on its behalf, every provider listed. items: $ref: '#/components/schemas/AgentToolUsage' type: array usage_this_month: $ref: '#/components/schemas/AgentUsage' required: - timezone - usage_this_month - daily_cap - tool_usage - balance - thinks_on - id - state - browser_tools - runs_on - model - cron_model - last_used_at - created_at 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_message_not_found - agent_message_pending - agent_not_found - 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 - default_skill_required - 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_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 - rate_limited - repository_not_reachable - request_canceled - request_timeout - request_too_large - service_unavailable - skill_slug_reserved - unauthenticated - unsupported_media_type - validation_failed - whatsapp_not_enabled 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 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 AgentDailyCap: additionalProperties: false properties: daily_cap_cents: description: >- The most the agent may spend from its owner's balance in a day, over every model call it makes on Aether inference and every tool call while tool calls are charged, in US 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 the timezone, until calls in flight settle under it, or until the cap is raised past them. format: int32 type: integer day: description: >- Today in the agent's timezone, as YYYY-MM-DD: the day spent_microdollars is for. pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ type: string spent_microdollars: description: >- What the agent's model calls, and its tool calls while they are charged, settled today, in millionths of a US dollar. format: int64 type: integer timezone: description: The owner's IANA timezone, whose midnight starts the next day. type: string required: - daily_cap_cents - day - timezone - spent_microdollars type: object AgentMemory: additionalProperties: false properties: notes: description: >- Your agent's notes, one entry each, in the order it keeps them; empty when unreadable. items: type: string type: array profile: description: >- What your agent keeps about you, one entry each, in the order it keeps them; empty when unreadable. items: type: string type: array read_at: description: When your agent's host last reported its memory. format: date-time type: string unreadable: description: >- Why your agent's host could not read its memory; absent when it could. type: string required: - notes - profile - read_at type: object AgentMemoryEdit: additionalProperties: false properties: action: description: 'add: a new entry; remove: the entry whose whole text is the edit''s.' enum: - add - remove type: string completed_at: description: When the edit was applied or refused; absent while pending. format: date-time type: string failure: description: >- Why the edit was refused: the entry would put the file past its limit, no entry is the removed text, or the host could not apply it. Present on a failed edit. type: string id: format: uuid type: string issued_at: format: date-time type: string state: description: >- pending: your agent has not applied it yet, or has not woken for it; completed: applied, and your agent's next turn reads it; failed: your agent's memory refused it, for failure. enum: - pending - completed - failed type: string target: description: 'notes: your agent''s notes; profile: what it keeps about you.' enum: - notes - profile type: string text: type: string required: - id - target - action - text - state - issued_at type: object AgentToolUsage: additionalProperties: false properties: amount_microdollars: description: >- Their cost at the provider's list price, in millionths of a US dollar, whoever pays it. format: int64 type: integer calls: description: The calls the provider answered. format: int64 type: integer charged: description: >- Whether your agent's calls to the provider are paid from your balance now, at its list price, and held to your agent's daily spend cap, whatever your agent thinks on. Off, Aether pays for them. type: boolean charged_microdollars: description: >- What of it was paid from your balance, in millionths of a US dollar; the rest Aether paid. format: int64 type: integer provider: description: >- The provider: firecrawl, which your agent's web search and page reading run on; browserbase, whose cloud sessions your agent's browser tools run on, one call a session. enum: - firecrawl - browserbase type: string required: - provider - calls - amount_microdollars - charged_microdollars - charged type: object 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 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 securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.