> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/developers/rest-api/agents/list-agents.md).

# List Agents

List agents.

Users can only access agents within their organisation. Returns a paginated list of agents. Optionally filter by name using the `search` query parameter and by status (enabled/disabled) using the `status` query parameter.

```json
{"openapi":"3.1.0","info":{"title":"Ibexa Agentic Marketing Platform","version":"0.1.0"},"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/api/v1/login/access-token"}}}},"schemas":{"AgentListResponseSchema":{"properties":{"agents":{"items":{"$ref":"#/components/schemas/AgentListItemResponseSchema"},"type":"array","title":"Agents"},"total_count":{"type":"integer","title":"Total Count"}},"type":"object","required":["agents","total_count"],"title":"AgentListResponseSchema","description":"Pydantic schema for agent list response."},"AgentListItemResponseSchema":{"properties":{"id":{"type":"integer","title":"Id"},"organisation_id":{"type":"integer","title":"Organisation Id"},"name":{"type":"string","title":"Name"},"identifier":{"type":"string","title":"Identifier"},"agent_type":{"type":"string","title":"Agent Type"},"is_enabled":{"type":"boolean","title":"Is Enabled"},"can_be_subagent":{"type":"boolean","title":"Can Be Subagent"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description"},"metrics":{"$ref":"#/components/schemas/AgentMetricsSchema"}},"type":"object","required":["id","organisation_id","name","identifier","agent_type","is_enabled","can_be_subagent","created_by","metrics"],"title":"AgentListItemResponseSchema","description":"Pydantic schema for agent list response."},"AgentMetricsSchema":{"properties":{"success_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Success Ratio"}},"type":"object","title":"AgentMetricsSchema","description":"Agent execution metrics."}}},"paths":{"/api/v1/agents/":{"get":{"tags":["agents","public"],"summary":"List Agents","description":"List agents.\n\nUsers can only access agents within their organisation.\nReturns a paginated list of agents.\nOptionally filter by name using the ``search`` query parameter and by\nstatus (enabled/disabled) using the ``status`` query parameter.","operationId":"agents-list_agents","parameters":[{"name":"skip","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of agents to skip","default":0,"title":"Skip"},"description":"Number of agents to skip"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of agents to return","default":25,"title":"Limit"},"description":"Maximum number of agents to return"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":3,"maxLength":128},{"type":"null"}],"description":"Search agents by name (case-insensitive substring match). Must be 3–128 characters.","title":"Search"},"description":"Search agents by name (case-insensitive substring match). Must be 3–128 characters."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["enabled","disabled"],"type":"string"},{"type":"null"}],"description":"Filter agents by status (`enabled` or `disabled`).","title":"Status"},"description":"Filter agents by status (`enabled` or `disabled`)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentListResponseSchema"}}}},"400":{"description":"Invalid request payload or parameters","content":{"application/json":{}}},"401":{"description":"User not authenticated","content":{"application/json":{}}}}}}}}
```