> ## Documentation Index > Fetch the complete documentation index at: https://docs.akua.dev/llms.txt > Use this file to discover all available pages before exploring further. # List agents > Lists agents in the workspace. ## OpenAPI ````yaml /openapi-public.json get /agents openapi: 3.1.0 info: title: Akua API version: 1.0.0 description: >- Public API for managing Akua workspaces, clusters, products, and installs. Authenticate with a workspace API token via the `Authorization: Bearer sk_akua_...` header. A workspace-owned token implies its workspace. Broad tokens select the active workspace via the optional `Akua-Context` header. contact: name: Akua API support email: support@akua.dev url: https://akua.dev/docs servers: - url: https://api.akua.dev/v1 description: Production security: [] tags: - name: Auth description: Authentication and token management. - name: Agents description: Agent identities and configuration. - name: Agent sessions description: Durable agent conversations and tasks. - name: Agent turns description: Submitted agent work and event emission. - name: Agent events description: Normalized agent event history and streams. - name: Custom domains description: Workspace custom domains and routing targets. - name: Cloudflare description: Cloudflare account credentials and gateway control. - name: Clusters description: Kubernetes clusters and cluster access operations. - name: ComputeConfigs description: Workspace compute provider configurations. - name: Entitlements description: Effective workspace capabilities and limits. - name: Dashboards description: Dashboard and widget resources. - name: Installs description: Installation and render operations. - name: Machines description: Compute machines and lifecycle events. - name: Notifications description: User notification state. - name: Offer Channels description: Private offer channels and policy versions. - name: Offers description: Marketplace offers and redemption tracking. - name: Operations description: Long-running operation status and controls. - name: Order Drafts description: Draft checkout orders and checkout sessions. - name: Organizations description: Organizations, memberships, and managed workspaces. - name: Packages description: Software packages, versions, and input schemas. - name: Products description: Marketplace product catalog resources. - name: Preview hostnames description: Install preview hostnames and routing state. - name: Quotas description: Workspace quota limits and usage. - name: Regions description: Available deployment regions. - name: Registry description: Container registry credentials and repositories. - name: Repository change requests description: Fork-backed repository change reviews and lifecycle actions. - name: Repositories description: Source repositories available to the workspace. - name: Secrets description: Workspace secrets and secret versions. - name: Snippets description: Reusable snippets and snippet runs. - name: Workspace subdomains description: Workspace subdomain identity. - name: Workspaces description: Workspace resources, members, and billing state. paths: /agents: get: tags: - Agents summary: List agents description: Lists agents in the workspace. operationId: agents.list parameters: - schema: type: string description: Pagination cursor from a previous response's `next_cursor`. required: false description: Pagination cursor from a previous response's `next_cursor`. name: cursor in: query - schema: type: integer minimum: 1 maximum: 100 default: 50 description: Items per page (1-100, default 50) example: 50 required: false description: Items per page (1-100, default 50) name: limit in: query - schema: type: string minLength: 1 maxLength: 53 description: >- Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace. example: ws_j572abc123def456 required: false description: >- Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace. name: akua-context in: header responses: '200': description: Agent list content: application/json: schema: $ref: '#/components/schemas/AgentList' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' security: - BearerAuth: [] components: schemas: AgentList: type: object properties: data: type: array items: $ref: '#/components/schemas/Agent' has_more: type: boolean description: True if more items exist after this page. next_cursor: type: - string - 'null' description: Opaque cursor for the next page, or null if no more pages. required: - data - has_more - next_cursor ApiErrorResponse: type: object properties: success: type: boolean enum: - false errors: type: array items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object properties: {} description: Always empty for error responses required: - success - errors - result Agent: type: object properties: id: type: string minLength: 1 maxLength: 54 workspace_id: type: string minLength: 1 maxLength: 53 organization_id: type: - string - 'null' minLength: 1 maxLength: 54 name: type: string description: type: - string - 'null' instructions: type: string state: type: string enum: - ENABLED - ARCHIVED origin: type: string enum: - PLATFORM - USER - SYSTEM capabilities: type: array items: type: string enum: - CHAT - CODING - AMBIENT ambient: $ref: '#/components/schemas/AgentAmbientConfig' model_policy: $ref: '#/components/schemas/AgentModelPolicy' created_by: type: string usage_summary: $ref: '#/components/schemas/AgentUsageSummary' created_at: type: integer minimum: 0 description: Unix timestamp (seconds) updated_at: type: integer minimum: 0 description: Unix timestamp (seconds) etag: type: string required: - id - workspace_id - organization_id - name - description - instructions - state - origin - capabilities - ambient - model_policy - created_by - usage_summary - created_at - updated_at - etag ApiErrorEntry: type: object properties: code: type: integer example: 7002 description: Machine-readable error code message: type: string example: Resource not found description: Human-readable error message path: type: array items: type: string example: - body - name description: Field path that caused the error, when applicable metadata: type: object additionalProperties: type: string required: - code - message AgentAmbientConfig: type: - object - 'null' properties: enabled: type: boolean policy: $ref: '#/components/schemas/AgentAmbientPolicy' triggers: type: array items: $ref: '#/components/schemas/AgentAmbientTrigger' maxItems: 50 required: - enabled - triggers AgentModelPolicy: type: object properties: default_model: type: string minLength: 1 maxLength: 120 billing_mode: type: string enum: - PLATFORM_SUBSCRIPTION - PLATFORM_API - WORKSPACE_BYOK credential_secret_id: type: - string - 'null' minLength: 1 maxLength: 54 allowed_models: type: array items: type: string minLength: 1 maxLength: 120 minItems: 1 maxItems: 50 severity_model_overrides: type: array items: type: object properties: severity: type: string enum: - LOW - MEDIUM - HIGH - CRITICAL model: type: string minLength: 1 maxLength: 120 required: - severity - model maxItems: 4 max_budget_cents: type: integer minimum: 0 budget_period: type: string enum: - DAY - WEEK - MONTH max_turn_budget_cents: type: integer minimum: 0 required: - default_model - billing_mode - credential_secret_id - allowed_models AgentUsageSummary: type: object properties: provider_cost_cents: type: integer minimum: 0 provider_token_count: type: integer minimum: 0 runtime_compute_seconds: type: number minimum: 0 runtime_storage_gb_hours: type: number minimum: 0 mcp_call_count: type: integer minimum: 0 api_call_count: type: integer minimum: 0 ambient_trigger_count: type: integer minimum: 0 required: - provider_cost_cents - provider_token_count - runtime_compute_seconds - runtime_storage_gb_hours - mcp_call_count - api_call_count - ambient_trigger_count AgentAmbientPolicy: type: object properties: remediation_mode: type: string enum: - READ_ONLY - APPROVAL_GATED allowed_resource_scopes: type: array items: $ref: '#/components/schemas/AgentAmbientResourceScope' maxItems: 100 max_spend_cents_per_trigger: type: integer minimum: 0 required: - remediation_mode - allowed_resource_scopes AgentAmbientTrigger: type: object properties: trigger_id: type: string minLength: 1 maxLength: 120 type: type: string enum: - INSTALL_STATE - CLUSTER_DEGRADATION - SECURITY_FINDING - QUOTA_PRESSURE - COST_ANOMALY - MANUAL_TEST state: type: string enum: - ENABLED - DISABLED severity_min: type: string enum: - LOW - MEDIUM - HIGH - CRITICAL runtime_hint: type: string enum: - AUTO - CODE_MODE - RETAINED_RUNTIME cooldown_seconds: type: integer exclusiveMinimum: 0 relationship_scope: anyOf: - type: object properties: type: type: string enum: - WORKSPACE required: - type - type: object properties: type: type: string enum: - SELLER_CUSTOMER seller_workspace_id: type: string minLength: 1 maxLength: 53 customer_workspace_id: type: string minLength: 1 maxLength: 53 support_relationship_id: type: string minLength: 1 maxLength: 200 required: - type - seller_workspace_id - customer_workspace_id resource_filters: type: array items: type: object properties: type: type: string minLength: 1 maxLength: 120 id: type: string minLength: 1 maxLength: 200 required: - type - id maxItems: 50 quiet_hours: type: object properties: timezone: type: string minLength: 1 maxLength: 120 start: type: string pattern: ^\d{2}:\d{2}$ end: type: string pattern: ^\d{2}:\d{2}$ required: - timezone - start - end required: - trigger_id - type - state - runtime_hint AgentAmbientResourceScope: type: object properties: type: type: string minLength: 1 maxLength: 120 id: type: string minLength: 1 maxLength: 200 required: - type securitySchemes: BearerAuth: type: http scheme: bearer description: >- workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens ````