> ## 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 agent profiles > Lists the project's agent profiles, newest first by default, filterable by name. Items include a summary of each profile's current config, not its full compiled definition. ## OpenAPI ````yaml /api-reference/openapi.yaml get /orgs/{orgID}/projects/{projectID}/agent-profiles 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}/projects/{projectID}/agent-profiles: parameters: - name: orgID in: path description: Organization ID (org_...). required: true schema: type: string pattern: ^org_[a-z2-7]{26}$ - name: projectID in: path description: Project ID (proj_...). required: true schema: type: string pattern: ^proj_[a-z2-7]{26}$ get: tags: - Configs and Profiles summary: List agent profiles description: >- Lists the project's agent profiles, newest first by default, filterable by name. Items include a summary of each profile's current config, not its full compiled definition. operationId: listAgentProfiles parameters: - $ref: '#/components/parameters/ResourceNameFilter' - $ref: '#/components/parameters/AgentProfileIncludeStats' - $ref: '#/components/parameters/AgentProfileStatsSince' - name: sort in: query schema: $ref: '#/components/schemas/ResourceListSort' - $ref: '#/components/parameters/PageLimit' - $ref: '#/components/parameters/PageCursor' responses: '200': description: Agent profiles in the project, newest first. content: application/json: schema: $ref: '#/components/schemas/ListAgentProfilesResponse' '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: 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. AgentProfileIncludeStats: name: include_stats in: query required: false schema: type: boolean description: >- Include each profile's `stats`, so a list can show instance counts and usage without a request per profile. AgentProfileStatsSince: name: stats_since in: query required: false schema: type: string format: date-time description: >- Start of the window `stats.usage` tallies, with `include_stats`. Omit to tally from the earliest recorded call. 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. schemas: 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 ListAgentProfilesResponse: type: object additionalProperties: false required: - data - next_cursor properties: data: type: array items: $ref: '#/components/schemas/AgentProfileSummary' next_cursor: type: - string - 'null' description: Opaque cursor for the next page, or null when this is the last page. AgentProfileSummary: type: object additionalProperties: false required: - id - org_id - project_id - name - current_config_id - current_generation - current_config - created_at - updated_at properties: id: $ref: '#/components/schemas/AgentProfileID' org_id: $ref: '#/components/schemas/OrganizationID' project_id: $ref: '#/components/schemas/ProjectID' name: $ref: '#/components/schemas/ResourceName' current_config_id: $ref: '#/components/schemas/AgentConfigID' current_generation: type: integer format: int32 created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' current_config: $ref: '#/components/schemas/AgentConfigSummary' stats: $ref: '#/components/schemas/AgentProfileStats' 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 - agent_backlog_full - 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 - agent_backlog_full - 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 AgentProfileID: type: string pattern: ^aprf_[a-z2-7]{26}$ OrganizationID: type: string pattern: ^org_[a-z2-7]{26}$ ProjectID: description: Project ID (proj_...). type: string pattern: ^proj_[a-z2-7]{26}$ 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. AgentConfigID: description: Agent config ID (acfg_...). type: string pattern: ^acfg_[a-z2-7]{26}$ Timestamp: type: string format: date-time AgentConfigSummary: type: object additionalProperties: false required: - id - org_id - project_id - effective_definition_hash - model - created_at properties: id: $ref: '#/components/schemas/AgentConfigID' org_id: $ref: '#/components/schemas/OrganizationID' project_id: $ref: '#/components/schemas/ProjectID' source: type: string source_format: type: string enum: - yaml - json effective_definition_hash: type: string model: $ref: '#/components/schemas/AgentConfigModel' instruction_hash: type: string created_at: $ref: '#/components/schemas/Timestamp' AgentProfileStats: type: object additionalProperties: false description: Present when the list was requested with `include_stats`. required: - agent_count - usage properties: agent_count: type: integer format: int64 minimum: 0 description: Unarchived top-level agents launched from the profile. usage: $ref: '#/components/schemas/UsageTotals' description: >- Model usage by the profile's agents and their subagents since `stats_since`. 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. AgentConfigModel: type: object additionalProperties: false required: - provider_config - name - provider_model_slug - configured_model_id - current_revision_id - api_format - api_variant - context_window_tokens - max_output_tokens - default_cache_retention - supports_tools - supports_reasoning - default_reasoning_effort - supported_reasoning_efforts - input_modalities - output_modalities properties: provider_config: $ref: '#/components/schemas/ResourceName' name: $ref: '#/components/schemas/ResourceName' description: >- Configured model name selected by this agent config, rendered from the current configured model record. provider_model_slug: type: string description: >- Exact provider model slug on the configured model's current revision at response time. configured_model_id: $ref: '#/components/schemas/ConfiguredModelID' current_revision_id: $ref: '#/components/schemas/ConfiguredModelRevisionID' api_format: $ref: '#/components/schemas/ModelAPIFormat' api_variant: $ref: '#/components/schemas/ModelProviderAPIVariantResponse' context_window_tokens: type: integer description: >- Effective context budget for input and output tokens after model, project, and agent settings are applied. Triggers compaction when estimated input exceeds the remaining budget after output and safety reserves. The turn fails if compaction cannot make it fit. max_output_tokens: type: - integer - 'null' description: >- Effective known output-token ceiling after model and project settings, or null when unknown. default_max_output_tokens: type: - integer - 'null' description: Effective per-request output-token cap sent to the provider. default_cache_retention: $ref: '#/components/schemas/ModelCacheRetention' supports_tools: type: boolean supports_reasoning: type: boolean default_reasoning_effort: type: string supported_reasoning_efforts: type: array items: type: string input_modalities: type: array items: type: string output_modalities: type: array items: type: string 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' ConfiguredModelID: type: string pattern: ^mdl_[a-z2-7]{26}$ ConfiguredModelRevisionID: type: string pattern: ^mrev_[a-z2-7]{26}$ ModelAPIFormat: description: >- Wire protocol the model endpoint speaks: openai-responses, openai-chat-completions, or anthropic-messages. type: string enum: - openai-responses - openai-chat-completions - anthropic-messages x-enum-varnames: - ModelAPIFormatOpenaiResponses - ModelAPIFormatOpenaiChatCompletions - ModelAPIFormatAnthropicMessages ModelProviderAPIVariantResponse: type: string x-extensible-enum: - default - openrouter - bedrock ModelCacheRetention: type: string description: >- Prompt-cache preference for model requests; `short` when omitted. `short` applies the route's default caching (explicit cache breakpoints where the provider requires them) and, where the route accepts one, a stable conversation key for cache-aware routing. `long` prefers the route's extended cache lifetime where one exists (currently Anthropic's one-hour cache, which on Bedrock requires Claude 4.5 or newer) and behaves like `short` elsewhere. `none` sends no Omnara-managed cache controls or conversation key; providers may still cache prefixes on their own. enum: - none - short - long 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 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.