> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyzr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Agents

Retrieve a paginated list of all voice agents associated with your authenticated organization or user account.

This endpoint returns detailed configurations for each agent, including their underlying engine settings, configured tools, avatar integrations, and prompt instructions.

<Warning>
  **Authentication Required** You must include your API key in the `x-api-key` header. Failing to do so will result in a `401 Unauthorized` error.
</Warning>

### Pagination Details

When fetching a large number of agents, use the query parameters to control your results:

* **`limit`**: Defines how many agents to return in a single request.
* **`offset`**: Defines how many agents to skip. For example, if you set `limit=10` and `offset=10`, you will retrieve the second "page" of your agents (items 11 through 20).

### The Agent `config` Object

The response payload contains an `agents` array. Each agent includes a heavily detailed `config` object which maps exactly to how the agent behaves in LiveKit. Key sections of this config include:

* **Engine Specs:** Outlines the specific LLM, STT (Speech-to-Text), and TTS (Text-to-Speech) pipelines powering the agent.
* **Knowledge Base:** Details any connected Lyzr RAG or Agentic RAG sources the agent uses for context.
* **Avatar & Audio:** Contains settings for visual avatars (e.g., HeyGen, Tavus, Simli) and background/ambient audio configurations.
* **Behavioral Prompts:** Defines the agent's specific role, goals, and dynamic variables injected at runtime.


## OpenAPI

````yaml get /agents
openapi: 3.0.3
info:
  title: Lyzr Voice LiveKit API
  version: 1.0.0
servers:
  - url: https://voice-livekit.studio.lyzr.ai/v1
security: []
paths:
  /agents:
    get:
      summary: List Agents
      description: List agents for the authenticated organization or user.
      parameters:
        - name: limit
          in: query
          description: The maximum number of agents to return.
          schema:
            type: integer
            example: 2
        - name: offset
          in: query
          description: >-
            The number of agents to skip before starting to collect the result
            set.
          schema:
            type: integer
            example: 1
      responses:
        '200':
          description: Agent list retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: 157e1979970ee35b248c32d4
                        config:
                          type: object
                          description: Comprehensive configuration settings for the agent.
                          properties:
                            agent_name:
                              type: string
                            agent_description:
                              type: string
                            engine:
                              type: object
                              properties:
                                kind:
                                  type: string
                                stt:
                                  type: string
                                llm:
                                  type: string
                                tts:
                                  type: string
                                voice_id:
                                  type: string
                                language:
                                  type: string
                            engine_pipeline:
                              type: object
                            engine_realtime:
                              type: object
                            prompt:
                              type: string
                            agent_role:
                              type: string
                            agent_goal:
                              type: string
                            agent_instructions:
                              type: string
                            dynamic_variables:
                              type: object
                              additionalProperties:
                                type: string
                            dynamic_variable_defaults:
                              type: object
                              additionalProperties:
                                type: string
                            conversation_start:
                              type: object
                            turn_detection:
                              type: string
                            noise_cancellation:
                              type: object
                            knowledge_base:
                              type: object
                            managed_agents:
                              type: object
                            tools:
                              type: array
                              items:
                                type: string
                            lyzr_tools:
                              type: array
                              items:
                                type: object
                            agent_id:
                              type: string
                            user_id:
                              type: string
                            session_id:
                              type: string
                            preemptive_generation:
                              type: boolean
                            pronunciation_correction:
                              type: boolean
                            pronunciation_rules:
                              type: object
                            audio_recording_enabled:
                              type: boolean
                            vad_enabled:
                              type: boolean
                            avatar:
                              type: object
                            background_audio:
                              type: object
                            corrections:
                              type: array
                              items:
                                type: object
                        createdAt:
                          type: string
                        updatedAt:
                          type: string
                        shared:
                          type: boolean
        '401':
          description: Missing or invalid x-api-key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  details:
                    type: string
        '502':
          description: Bad Gateway - Failed to resolve organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Failed to resolve org from Pagos
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````