> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-beta.getzep.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-beta.getzep.com/_mcp/server.

# List Agents

POST https://api.getzep.com/api/v4/agents/list
Content-Type: application/json

Reference: https://docs-beta.getzep.com/sdk-reference/agent/list

## Authentication

- `Authorization` header (required) (prefixed with ` Api-Key  `) — Type "Api-Key" followed by a space and the project API key.

## Request

### Query parameters

- `limit` (integer, optional) — Page size (maximum 100)
- `cursor` (string, optional) — Opaque page cursor

### Body (application/json)

This endpoint expects a v4.AgentListRequest.

- `agent_id` (string, optional) — Filters to the exact developer-assigned Agent identifier.
- `deployment_id` (string, optional) — Filters to the exact deployment identifier.
- `metadata` (map from string to any, optional) — Filters to Agents whose metadata contains these key-value pairs.
- `status` (enum, optional) — Filters to lifecycle status. Omit to include every status.
  - Allowed values: `active`, `deleting`, `deletion_failed`
- `version` (string, optional) — Filters to the exact deployment version.

## Response

### 200

OK

- `items` (list of v4.Agent, optional) — The Agents on this page.
- `next_cursor` (string, optional) — Opaque cursor for retrieving the next page, present only when more results are available.
- `total_size` (integer, optional) — The total number of Agents matching the filters and authorization scope.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (v4.ErrorBody, optional)

### 401 Unauthorized Error

Unauthorized

- `error` (v4.ErrorBody, optional)

### 403 Forbidden Error

Forbidden

- `error` (v4.ErrorBody, optional)

### 404 Not Found Error

Not Found

- `error` (v4.ErrorBody, optional)

## Types

### v4.Agent

- `agent_id` (string, optional) — The developer-assigned Agent identifier, unique within the project.
- `created_at` (string, optional) — The time the Agent was created.
- `deployment_id` (string, optional) — The customer deployment this Agent represents.
- `description` (string, optional) — A human-readable description of the Agent.
- `memory_settings` (v4.AgentMemorySettings, optional) — Agent Memory capture, compilation, and promotion settings.
- `metadata` (map from string to any, optional) — Developer metadata used to organize and filter Agents.
- `name` (string, optional) — The Agent's display name.
- `revision` (integer, optional) — The revision required by the next update or delete request.
- `security_domain` (string, optional) — The immutable boundary within which Skills may be synthesized.
- `status` (enum, optional) — The current lifecycle status.
  - Allowed values: `active`, `deleting`, `deletion_failed`
- `updated_at` (string, optional) — The time the Agent was last updated.
- `uuid` (string, optional) — The stable identifier of the Agent.
- `version` (string, optional) — The customer deployment version this Agent represents.

### v4.ErrorBody

- `code` (string, optional)
- `details` (map from string to any, optional)
- `message` (string, optional)
- `param` (string, optional)
- `request_id` (string, optional)

### v4.AgentMemorySettings

- `admission_evaluation_requirements` (list of v4.AgentMemoryEvaluationPolicy, optional)
- `approval` (enum, optional)
  - Allowed values: `manual`, `auto`
- `approval_minimum_attempt_families` (integer, optional)
- `approval_required_tools` (list of string, optional) — ApprovalRequiredTools lists the tool names that need a member approval in auto approval. A generated Skill that uses one of these tools waits for a member. The default is an empty list.
- `auto_approval_task_families` (list of string, optional)
- `compilation_mode` (enum, optional)
  - Allowed values: `scheduled`, `manual`, `on_close`
- `provisional_expiry_days` (integer, optional) — ProvisionalExpiryDays is the period after which Zep retires a provisional Skill that no application used. When it is not set, provisional Skills do not expire.
- `provisional_skill_limit` (integer, optional) — ProvisionalSkillLimit is the maximum count of provisional Skills in one task family. Over the limit, a new provisional Skill waits for a member. When it is not set, no limit applies.
- `retention_days` (integer, optional)

### v4.AgentMemoryEvaluationPolicy

- `requirements` (list of v4.AgentMemoryEvaluationRequirement, required)
- `task_family` (string, required)

### v4.AgentMemoryEvaluationRequirement

- `evaluated_by` (string, required)
- `evaluator_version` (string, required)
- `result` (string, required)
- `controlled` (boolean, optional)
- `environment` (string, optional)

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "items": [
    {
      "agent_id": "string",
      "created_at": "string",
      "deployment_id": "string",
      "description": "string",
      "memory_settings": {
        "admission_evaluation_requirements": [
          {
            "requirements": [
              {
                "evaluated_by": "string",
                "evaluator_version": "string",
                "result": "string",
                "controlled": true,
                "environment": "string"
              }
            ],
            "task_family": "string"
          }
        ],
        "approval": "manual",
        "approval_minimum_attempt_families": 1,
        "approval_required_tools": [
          "string"
        ],
        "auto_approval_task_families": [
          "string"
        ],
        "compilation_mode": "scheduled",
        "provisional_expiry_days": 1,
        "provisional_skill_limit": 1,
        "retention_days": 1
      },
      "metadata": {},
      "name": "string",
      "revision": 1,
      "security_domain": "string",
      "status": "active",
      "updated_at": "string",
      "uuid": "string",
      "version": "string"
    }
  ],
  "next_cursor": "string",
  "total_size": 1
}
```