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

# List Agents

> Retrieves a paginated list of agents (supports filtering and sorting).



## OpenAPI

````yaml /api-reference/openapi.json get /api/agents
openapi: 3.1.0
info:
  title: Ello.AI API
  description: API for managing agents and calls in Ello.AI
  version: 1.0.0
servers:
  - url: https://api.getello.ai/
security: []
paths:
  /api/agents:
    get:
      tags:
        - Agents
      summary: List Agents
      description: Retrieves a paginated list of agents (supports filtering and sorting).
      operationId: listAgents
      parameters:
        - name: workspace_id
          in: query
          required: false
          schema:
            type: string
            example: 6970c2f3948cfbce1932d99d
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            example: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            example: 10
        - name: category
          in: query
          required: false
          schema:
            type: string
            example: general
        - name: search
          in: query
          required: false
          schema:
            type: string
            example: sales
        - name: sort_field
          in: query
          required: false
          schema:
            type: string
            enum:
              - name
              - type
              - status
              - createdAt
              - updatedAt
            example: updatedAt
        - name: sort_order
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            example: desc
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2026-04-01T00:00:00.000Z'
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2026-04-03T23:59:59.999Z'
        - name: filters
          in: query
          required: false
          schema:
            oneOf:
              - type: object
                properties:
                  status:
                    type: boolean
                    example: true
                  type:
                    type: string
                    enum:
                      - inbound
                      - outbound
                      - chat
                      - hybrid
                    example: hybrid
              - type: string
                description: JSON stringified filters object
                example: '{"status":true,"type":"hybrid"}'
      responses:
        '200':
          description: Agents retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Assistants retrieved successfully
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: 698054b94168f285f5d3467b
                        name:
                          type: string
                          example: My Hybrid Agent
                        type:
                          type: string
                          example: hybrid
                        updatedAt:
                          type: string
                          format: date-time
                          example: '2026-03-19T08:12:33.503000Z'
                        voiceEngine:
                          type: string
                          example: sarvam
                        phoneNumber:
                          type:
                            - string
                            - 'null'
                          example: '+919247519114'
                        status:
                          type: boolean
                          example: true
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                        example: 1
                      limit:
                        type: integer
                        example: 10
                      total:
                        type: integer
                        example: 3
                      totalPages:
                        type: integer
                        example: 1
                      hasNextPage:
                        type: boolean
                        example: false
                      hasPrevPage:
                        type: boolean
                        example: false
        '400':
          description: Bad Request / Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: Validation Error
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          example: query.limit
                        message:
                          type: string
                          example: '"limit" must be less than or equal to 100'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: Unauthorized access
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: This route requires a user token without scope
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Error while fetching assistants
                  error:
                    type: object
                    properties:
                      details:
                        type: string
                        example: Some internal error message
      security:
        - apiKey: []
        - bearerAuth: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````