> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnara.com/llms.txt > Use this file to discover all available pages before exploring further. # List agents across projects > Lists agents in every project of the organization where the caller can read agents. Each agent carries its project_id. Items are ordered by created_at descending, then id descending. ## OpenAPI ````yaml /api-reference/openapi.yaml get /orgs/{orgID}/agents openapi: 3.1.2 info: title: Omnara API version: 0.1.0 description: Public HTTP API contract for Omnara. servers: - url: https://api.omnara.com/v1 description: Hosted Omnara - url: /api/v1 description: Self-hosted Omnara, relative to the deployment origin security: - bearerAuth: [] - browserSessionCookie: [] tags: - name: Agents description: >- Launch agents, send inputs, manage the input backlog, and work with tool calls. externalDocs: description: Guide url: https://docs.omnara.com/agents/overview - name: Interactions description: List and resolve the approvals and questions that pause an agent. externalDocs: description: Guide url: https://docs.omnara.com/events/interactions - name: Actors description: Attribute agent inputs and interaction responses to external users. externalDocs: description: Guide url: >- https://docs.omnara.com/events/sending-input#who-said-that-actors-and-attribution - name: Events description: Read or stream the agent timeline, list turns, and download artifacts. externalDocs: description: Guide url: https://docs.omnara.com/events/streaming - name: Configs and Profiles description: >- Create agent configs, manage reusable launch profiles, and set up integrations. externalDocs: description: Guide url: https://docs.omnara.com/agents/configuration - name: Integrations description: >- Connect project integrations, route conversations, and manage launch settings. externalDocs: description: Guide url: https://docs.omnara.com/integrations/overview - name: Models description: Configure model providers and models, and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/organization/model-providers - name: Machines description: Register machines, control project access, and manage daemon tokens. externalDocs: description: Guide url: https://docs.omnara.com/machines/connect - name: Machine Pools description: Define machine pools and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/machines/pools - name: Secrets description: >- Manage secret ownership and versions, and inspect or grant project availability. externalDocs: description: Guide url: https://docs.omnara.com/organization/secrets - name: Skills description: Manage versioned skill ownership and load skill instructions on demand. externalDocs: description: Guide url: https://docs.omnara.com/tools/skills - name: Organizations and Projects description: Create organizations and projects and manage membership. externalDocs: description: Guide url: https://docs.omnara.com/organization/members - name: Users and API Keys description: >- The authenticated user, personal and organization API keys, and invitations. externalDocs: description: Guide url: https://docs.omnara.com/api/authentication - name: Machine Daemon description: Routes the Omnara machine daemon uses to connect a machine. paths: /orgs/{orgID}/agents: parameters: - name: orgID in: path required: true schema: $ref: '#/components/schemas/OrganizationID' get: tags: - Agents summary: List agents across projects description: >- Lists agents in every project of the organization where the caller can read agents. Each agent carries its project_id. Items are ordered by created_at descending, then id descending. operationId: listOrgAgents parameters: - $ref: '#/components/parameters/ResourceNameFilter' - name: agent_profile_id in: query description: Return only agents launched from this agent profile. schema: $ref: '#/components/schemas/AgentProfileID' - name: parent_agent_id in: query description: Return only subagents spawned by this agent. schema: $ref: '#/components/schemas/AgentID' - name: include_subagents in: query description: >- Include subagents alongside top-level agents. Defaults to false, so only agents without a parent are returned unless parent_agent_id is set. schema: type: boolean - name: include_archived in: query description: Include archived agents. Defaults to false. schema: type: boolean - $ref: '#/components/parameters/AgentIncludeUsage' - name: sort in: query schema: $ref: '#/components/schemas/ResourceListSort' - $ref: '#/components/parameters/PageLimit' - $ref: '#/components/parameters/PageCursor' responses: '200': description: Agents across the caller's readable projects, newest first. content: application/json: schema: $ref: '#/components/schemas/ListAgentsResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '503': $ref: '#/components/responses/ServiceUnavailable' 4XX: $ref: '#/components/responses/ClientError' 5XX: $ref: '#/components/responses/ServerError' components: schemas: OrganizationID: type: string pattern: ^org_[a-z2-7]{26}$ AgentProfileID: type: string pattern: ^aprf_[a-z2-7]{26}$ AgentID: type: string pattern: ^agt_[a-z2-7]{26}$ ResourceListSort: type: string description: >- Sort order for named resources that expose created and modified timestamps. default: '-created_at' enum: - name - '-name' - '-updated_at' - updated_at - '-created_at' - created_at ListAgentsResponse: type: object additionalProperties: false required: - data - next_cursor properties: data: type: array items: $ref: '#/components/schemas/Agent' next_cursor: type: - string - 'null' description: Opaque cursor for the next page, or null when this is the last page. Agent: type: object additionalProperties: false required: - id - org_id - project_id - state - name - created_at - updated_at properties: id: $ref: '#/components/schemas/AgentID' org_id: $ref: '#/components/schemas/OrganizationID' project_id: $ref: '#/components/schemas/ProjectID' agent_profile_id: $ref: '#/components/schemas/AgentProfileID' state: type: string enum: - active - archived name: $ref: '#/components/schemas/AgentName' integration_target: $ref: '#/components/schemas/IntegrationTarget' description: >- Selected question/approval destination. Automatic mode updates it when content inputs are admitted. Prompts use it only while the integration and handler remain eligible. It is not launch provenance or permission to post. current_config_id: $ref: '#/components/schemas/AgentConfigID' model: $ref: '#/components/schemas/AgentModel' parent_agent_id: $ref: '#/components/schemas/AgentID' description: Set when this agent is a subagent spawned by another agent. subagent_key: description: The `subagents` key this agent was spawned from. type: string activity: $ref: '#/components/schemas/AgentActivity' description: Current activity, present on list responses. usage: $ref: '#/components/schemas/UsageTotals' description: >- All-time model usage by the agent and its subagents. Present when the list was requested with `include_usage`. created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' archived_at: $ref: '#/components/schemas/Timestamp' Error: type: object additionalProperties: false required: - error - code properties: error: type: string description: Human-readable error message. Do not match on it programmatically. current_digest: type: string pattern: ^sha256:[0-9a-f]{64}$ description: >- Current file digest for file_content_conflict or expected_digest_required; absent if the file no longer exists. A replacement must be confirmed before retrying with this digest. issues: type: array description: >- Field-level problems when a submitted document (such as an agent config source) failed validation. Absent for errors that are not about a specific field. items: $ref: '#/components/schemas/AgentConfigErrorIssue' code: type: string description: Stable error code for programmatic handling. x-go-type: ErrorCode x-extensible-enum: - invalid_request - unauthorized - forbidden - not_found - conflict - file_content_conflict - file_read_only - expected_digest_required - not_a_file - gone - request_too_large - unsupported_media_type - unprocessable - upstream_unavailable - rate_limited - internal_error - service_unavailable - idempotency_key_conflict - state_transition_conflict - managed_work_admission_denied - pending_work - not_wake_capable - daemon_runtime_unregistered - validation_failed - csrf_check_failed - authentication_unavailable ClientErrorCode: type: string description: >- Stable error code carried by 4XX statuses. Subset of the Error code enum whose statuses are client errors. x-extensible-enum: - invalid_request - validation_failed - unauthorized - forbidden - csrf_check_failed - not_found - conflict - file_content_conflict - file_read_only - expected_digest_required - not_a_file - idempotency_key_conflict - state_transition_conflict - pending_work - not_wake_capable - gone - daemon_runtime_unregistered - request_too_large - unsupported_media_type - unprocessable - upstream_unavailable - rate_limited ServerErrorCode: type: string description: >- Stable error code carried by 5XX statuses. Subset of the Error code enum whose statuses are server errors. x-extensible-enum: - internal_error - service_unavailable - authentication_unavailable ProjectID: type: string pattern: ^proj_[a-z2-7]{26}$ AgentName: type: string maxLength: 64 x-omnara-unicode-normalization: NFC description: >- Agent name. Empty means the agent is unnamed; non-empty values use the ResourceName policy. IntegrationTarget: type: object additionalProperties: false required: - provider - conversation - display_name properties: provider: type: string conversation: $ref: '#/components/schemas/IntegrationConversation' display_name: type: string provider_uri: type: string format: uri AgentConfigID: type: string pattern: ^acfg_[a-z2-7]{26}$ AgentModel: type: object additionalProperties: false required: - provider_config - name properties: provider_config: $ref: '#/components/schemas/ResourceName' name: $ref: '#/components/schemas/ResourceName' AgentActivity: type: object additionalProperties: false required: - state - last_activity_at properties: state: description: >- running while the agent has work in progress, waiting_on_interaction while it has an open question or permission request, idle otherwise, and archived once the agent is archived. type: string enum: - running - idle - waiting_on_interaction - archived last_activity_at: $ref: '#/components/schemas/Timestamp' description: >- When the agent's latest event was recorded, or its creation time before any event. UsageTotals: type: object additionalProperties: false required: - model_calls - tokens - cost properties: model_calls: type: integer format: int64 minimum: 0 description: Model calls that recorded token usage or a provider-reported cost. tokens: $ref: '#/components/schemas/UsageTokenTotals' cost: $ref: '#/components/schemas/UsageCostTotals' Timestamp: type: string format: date-time AgentConfigErrorIssue: type: object additionalProperties: false required: - path - message properties: path: type: string description: >- JSON Pointer (RFC 6901) to the offending field in the submitted document. An empty string refers to the whole document. message: type: string description: Human-readable description of the problem with this field. line: type: integer minimum: 1 description: >- 1-based line of the offending field in the submitted source, when it can be located. column: type: integer minimum: 1 description: >- 1-based column of the offending field in the submitted source, when it can be located. IntegrationConversation: type: object additionalProperties: true x-go-type: json.RawMessage x-go-type-skip-optional-pointer: true description: >- One concrete provider address, validated by the integration's capabilities.subscription.conversation_schema. Slack uses channel_id and optional thread_ts; Discord uses channel_id for a channel or thread_id for a thread; GitHub uses repository_id and pull_request. Discord accepts optional parent channel_id and guild_id alongside thread_id and validates their ID format, but subscription creation does not verify them against Discord or retain them as routing restrictions. Only thread_id is retained in a canonical thread address and returned by create/list responses. No credentials or runtime state. ResourceName: type: string minLength: 1 maxLength: 64 x-omnara-unicode-normalization: NFC description: >- Human-readable name. Spaces and punctuation are allowed; leading or trailing whitespace and invisible or control characters are not. UsageTokenTotals: type: object additionalProperties: false description: >- Summed token counts across the tallied model calls. Input totals are the sum of uncached, cache-read, and cache-write tokens; output totals include reasoning tokens. required: - input_tokens_total - uncached_input_tokens - cache_read_input_tokens - cache_write_input_tokens - output_tokens_total - reasoning_output_tokens properties: input_tokens_total: type: integer format: int64 minimum: 0 uncached_input_tokens: type: integer format: int64 minimum: 0 cache_read_input_tokens: type: integer format: int64 minimum: 0 cache_write_input_tokens: type: integer format: int64 minimum: 0 output_tokens_total: type: integer format: int64 minimum: 0 reasoning_output_tokens: type: integer format: int64 minimum: 0 UsageCostTotals: type: object additionalProperties: false required: - provider_reported_usd - model_calls_with_reported_cost properties: provider_reported_usd: type: string description: >- Exact decimal sum in USD of the costs the provider reported for the tallied model calls. Calls whose provider reported no cost contribute nothing; compare model_calls_with_reported_cost against model_calls to see how complete the figure is. pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$ model_calls_with_reported_cost: type: integer format: int64 minimum: 0 parameters: ResourceNameFilter: name: name in: query required: false schema: type: string minLength: 1 maxLength: 200 description: >- Case-insensitive glob over the list's logical name. `*` matches zero or more characters, `?` matches one character, and `\` escapes a wildcard. AgentIncludeUsage: name: include_usage in: query required: false schema: type: boolean description: >- Include each agent's `usage`, so a list can show costs without a request per agent. PageLimit: name: limit in: query required: false schema: type: integer format: int32 minimum: 1 maximum: 100 default: 50 description: Maximum number of items to return in one page. PageCursor: name: cursor in: query required: false schema: type: string maxLength: 1024 description: >- Opaque pagination cursor from a previous response's next_cursor. Omit for the first page. responses: BadRequest: description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication is required or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The authenticated principal is not authorized. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found or is not visible. content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: The service dependency required to satisfy the request is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' ClientError: description: >- Any other client error. The body carries the shared Error envelope restricted to client error codes; statuses with a dedicated response above are documented precisely. content: application/json: schema: type: object additionalProperties: false required: - error - code properties: error: type: string description: >- Human-readable error message. Do not match on it programmatically. code: $ref: '#/components/schemas/ClientErrorCode' ServerError: description: >- Any other server error. The body carries the shared Error envelope restricted to server error codes. content: application/json: schema: type: object additionalProperties: false required: - error - code properties: error: type: string description: >- Human-readable error message. Do not match on it programmatically. code: $ref: '#/components/schemas/ServerErrorCode' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Omnara personal or organization access token description: An opaque Omnara personal or organization bearer token. browserSessionCookie: type: apiKey in: cookie name: __Host-omnara_session description: >- Browser session cookie. HTTPS deployments use __Host-omnara_session; local HTTP development uses omnara_session. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.