# Get all Agents

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /api/v2/agents/:
    get:
      summary: Get all Agents
      deprecated: false
      description: >-
        Retrieves a list of agents with support for pagination and advanced
        filters, enabling users to explore and manage agents effectively.


        Purpose:

        - Allows users to fetch agents with optional filters such as search
        query, carousel ID, and teammate view.

        - Supports pagination and tag-based filtering to refine large datasets.


        Query Parameters:

        - query (string, optional): Search term to filter agents by name.

        - carousel_id (string, optional): Filter agents associated with a
        specific carousel.

        - published_as_teammate (boolean, optional): Filter agents published as
        teammates.

        - tags (list of strings, optional): Filter agents by associated tags.

        - paginated (boolean, optional): Toggle between paginated or full
        results.

        - page (int, optional): Page number (used if paginated=true).

        - items_per_page (int, optional): Items per page (used if
        paginated=true).

        - project_id (int, optional): Filter agents by project ID. Can pass
        comma separated values.

        - user_id (int, optional): Filter agents by user ID. Can pass comma
        separated values.

        - agent_ids (int, optional): Filter agents by agent ID. Can pass comma
        separated values.

        - status (string, optional): Filter agents by status (e.g., "Live",
        "Drafted", etc.).

        - sort_by (string, optional): Sort by field. Default is "-created_on".
        Possible values: "agent_name", "user_email", "created_on", "created_by".
        Add "-" before the field name to order in descending order.

        - fields (string, optional): Comma-separated list of response fields to
        include per agent (e.g. "id,agent_name"). When omitted, every field is
        returned.

        - include_default_agent (boolean, optional): Include the organization's
        default agent in the results. Excluded by default; it is exposed
        separately via /agents/default-agent. Still excluded when
        published_as_teammate=true, since the default agent is not published as
        a teammate.


        Request Headers:

        - X-Authorization-Consistency-Token (string, optional): Authorization
        consistency token for read-after-write consistency. Pass the token
        received from a previous write operation to ensure this read reflects
        that write.


        Returns:

        - A list of serialized agents based on applied filters.

        - Supports both paginated and unpaginated responses based on user
        preference.

        - If no agents are found or if an error occurs, returns an appropriate
        error response.


        Current Version:

        - 2.0.0


        Changelog:

        - v2.0.0: Agents are now organized under projects rather than teams. The
        team_id filter parameter
          has been removed. Use project_id to filter agents by project, which does not require team-level filtering.
      operationId: api_v2_agents_list_retrieve
      tags:
        - Agents
        - Agents
        - v2
      parameters:
        - name: agent_ids
          in: query
          description: >-
            Filter agents by agent ID. Can pass comma separated values
            (Optional).
          required: false
          example: ''
          schema:
            type: string
            default: ''
        - name: carousel_id
          in: query
          description: Filter agents by carousel ID.
          required: false
          example: 0
          schema:
            type: integer
            nullable: true
        - name: fields
          in: query
          description: >-
            Comma-separated list of response fields to include per agent (e.g.
            'id,agent_name'). When omitted, the full agent object is returned.
          required: false
          example: ''
          schema:
            type: string
            default: ''
        - name: include_default_agent
          in: query
          description: >-
            Include the organization's default agent in the results. It is
            excluded by default and exposed separately via
            /agents/default-agent. Note that the default agent is not published
            as a teammate, so it is still excluded when
            published_as_teammate=true. Accepted values: true, false, 1, 0.
            Default is False.
          required: false
          example: ''
          schema:
            type: boolean
            default: false
        - name: items_per_page
          in: query
          description: Number of items per page. Default is 50.
          required: false
          example: 0
          schema:
            type: integer
            minimum: 1
            default: 50
        - name: page
          in: query
          description: The page number to retrieve. Default is 1.
          required: false
          example: 0
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: paginated
          in: query
          description: >-
            Enable pagination. Accepted values: true, false, 1, 0. Default is
            False.
          required: false
          example: ''
          schema:
            type: boolean
            default: false
        - name: project_id
          in: query
          description: Filter agents by project ID. Can pass comma separated values.
          required: false
          example: ''
          schema:
            type: string
        - name: published_as_teammate
          in: query
          description: Filter agents published as teammate.
          required: false
          example: ''
          schema:
            type: boolean
            default: false
        - name: query
          in: query
          description: Search term to filter agents by name.
          required: false
          example: ''
          schema:
            type: string
            default: ''
        - name: sort_by
          in: query
          description: >-
            Sort by field. Default is '-created_on'. Possible values:
            'agent_name', 'user_email', 'created_on', 'created_by'. Add '-'
            before the field name to order in descending order.
          required: false
          example: ''
          schema:
            type: string
            default: '-created_on'
        - name: status
          in: query
          description: Filter agents by status (e.g., 'Live', 'Draft', etc.)
          required: false
          example: ''
          schema:
            type: string
            default: ''
        - name: tags
          in: query
          description: Filter agents by tags. Can pass comma separated values (Optional).
          required: false
          example: ''
          schema:
            type: string
            default: ''
        - name: user_id
          in: query
          description: Filter agents by user ID. Can pass comma separated values.
          required: false
          example: ''
          schema:
            type: string
        - name: Organization-Id
          in: header
          description: 'ID of the organization. Optional. '
          required: false
          example: 0
          schema:
            type: integer
        - name: Ocp-Apim-Subscription-Key
          in: header
          description: API KEY FOR EJENTO APIs
          required: true
          example: '{{your-api-key}}'
          schema:
            type: string
            default: '{{your-api-key}}'
        - name: Authorization
          in: header
          description: AUTH TOKEN
          example: Bearer {{your-access-token}}
          schema:
            type: string
            default: Bearer {{your-access-token}}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentListGetResponseSchema_V2'
          headers: {}
          x-apidog-name: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentListGet400ResponseSchema_V2'
          headers: {}
          x-apidog-name: Bad Request
        '403':
          description: >-
            The subscription key belongs to a different organization than the
            one this request names, or you do not have access to the
            organization it names. An organization that does not exist returns
            the same response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: false
                  message:
                    type: string
                  data:
                    type: object
                    default: {}
                    x-apidog-orders: []
                    properties: {}
                    x-apidog-ignore-properties: []
                required:
                  - success
                  - message
                  - data
                x-apidog-orders:
                  - success
                  - message
                  - data
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: Server Error
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentListGet500ResponseSchema_V2'
          headers: {}
          x-apidog-name: ''
        '503':
          description: >-
            The organization for this request could not be verified. Try again
            later.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: false
                  message:
                    type: string
                  data:
                    type: object
                    default: {}
                    x-apidog-orders: []
                    properties: {}
                    x-apidog-ignore-properties: []
                required:
                  - success
                  - message
                  - data
                x-apidog-orders:
                  - success
                  - message
                  - data
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: ''
      security: []
      x-apidog-folder: Agents
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/998119/apis/api-19061047-run
components:
  schemas:
    AgentListGetResponseSchema_V2:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          $ref: '#/components/schemas/AgentListGetResponseSerializer_V2'
      required:
        - success
        - message
        - data
      x-apidog-orders:
        - success
        - message
        - data
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    AgentListGetResponseSerializer_V2:
      type: object
      properties:
        count:
          type: integer
        num_pages:
          type: integer
        current_page:
          type: integer
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentListAgentSerializer_V2'
      required:
        - agents
      x-apidog-orders:
        - count
        - num_pages
        - current_page
        - agents
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    AgentListAgentSerializer_V2:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        created_by:
          type: string
          readOnly: true
          nullable: true
        modified_by:
          type: string
          readOnly: true
          nullable: true
        created_on:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        modified_on:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        user:
          $ref: '#/components/schemas/AgentList_User'
        agent_type:
          $ref: '#/components/schemas/AgentList_AgentType'
        instructions:
          type: array
          items:
            $ref: '#/components/schemas/AgentList_Instruction'
          readOnly: true
        project:
          $ref: '#/components/schemas/AgentList_Project'
        connected_tool_names:
          type: array
          items:
            type: string
          readOnly: true
        tags:
          type: array
          items:
            type: string
        character_voice:
          allOf:
            - $ref: '#/components/schemas/AgentList_CharacterVoice'
          type: 'null'
        pattern:
          allOf:
            - $ref: '#/components/schemas/Pattern'
          readOnly: true
        staging_agent_id:
          type: string
          readOnly: true
        agent_name:
          type: string
          maxLength: 256
        industry_area:
          type: string
          maxLength: 256
        domain:
          type: string
          nullable: true
        sample_q1:
          type: string
          maxLength: 1024
          nullable: true
        sample_q2:
          type: string
          maxLength: 1024
          nullable: true
        sample_q3:
          type: string
          maxLength: 1024
          nullable: true
        sample_q4:
          type: string
          maxLength: 1024
          nullable: true
        prefix_prompt:
          type: string
          nullable: true
        alias:
          type: string
          maxLength: 512
          nullable: true
        is_active:
          type: boolean
        is_deleted:
          type: boolean
        agent_image:
          type: string
          nullable: true
        access:
          type: string
          maxLength: 512
        status:
          type: string
          maxLength: 512
        caching_enabled:
          type: boolean
        chunk_count:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        attachment_chunk_count:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        attachment_chunking:
          type: boolean
        react_enabled:
          type: boolean
        react_max_iteration_count:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        reasoning_mode:
          enum:
            - react
            - react_reflect
            - codeact
          type: string
          description: |-
            * `react` - ReAct
            * `react_reflect` - Reflection
            * `codeact` - CodeAct
        call_enabled:
          type: boolean
        is_published_as_teammate:
          type: boolean
          description: Indicates if the agent is published as a teammate on the platform
        chat_count:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          description: Cached count of chats for performance
        likes_count:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          description: Cached count of likes for performance
        conversation_starter_enabled:
          type: boolean
        enable_embed:
          type: boolean
        langfuse_tracing_enabled:
          type: boolean
          description: Enable Langfuse tracing for this agent
        parent:
          type: integer
          nullable: true
        llm_config:
          type: integer
          nullable: true
        cloned_from:
          type: integer
          nullable: true
        voice_llm_config:
          type: integer
          nullable: true
      required:
        - id
        - created_by
        - modified_by
        - created_on
        - modified_on
        - user
        - agent_type
        - instructions
        - project
        - connected_tool_names
        - tags
        - pattern
        - staging_agent_id
        - agent_name
        - industry_area
      x-apidog-orders:
        - id
        - created_by
        - modified_by
        - created_on
        - modified_on
        - user
        - agent_type
        - instructions
        - project
        - connected_tool_names
        - tags
        - character_voice
        - pattern
        - staging_agent_id
        - agent_name
        - industry_area
        - domain
        - sample_q1
        - sample_q2
        - sample_q3
        - sample_q4
        - prefix_prompt
        - alias
        - is_active
        - is_deleted
        - agent_image
        - access
        - status
        - caching_enabled
        - chunk_count
        - attachment_chunk_count
        - attachment_chunking
        - react_enabled
        - react_max_iteration_count
        - reasoning_mode
        - call_enabled
        - is_published_as_teammate
        - chat_count
        - likes_count
        - conversation_starter_enabled
        - enable_embed
        - langfuse_tracing_enabled
        - parent
        - llm_config
        - cloned_from
        - voice_llm_config
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    Pattern:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          maxLength: 256
        description:
          type: string
          nullable: true
      required:
        - id
        - name
      x-apidog-orders:
        - id
        - name
        - description
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    AgentList_CharacterVoice:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        voice_name:
          type: string
          maxLength: 512
        voice_identifier:
          type: string
          maxLength: 512
        gender:
          enum:
            - male
            - female
          type: string
          description: |-
            * `male` - Male
            * `female` - Female
      required:
        - id
        - voice_name
        - voice_identifier
        - gender
      x-apidog-orders:
        - id
        - voice_name
        - voice_identifier
        - gender
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    AgentList_Project:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        project_name:
          type: string
          maxLength: 256
      required:
        - id
        - project_name
      x-apidog-orders:
        - id
        - project_name
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    AgentList_Instruction:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        created_by:
          type: string
          readOnly: true
          nullable: true
        modified_by:
          type: string
          readOnly: true
          nullable: true
        created_on:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        modified_on:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        instruction:
          type: string
        is_deleted:
          type: boolean
        parent:
          type: integer
          nullable: true
        agent:
          type: integer
      required:
        - id
        - created_by
        - modified_by
        - created_on
        - modified_on
        - instruction
        - agent
      x-apidog-orders:
        - id
        - created_by
        - modified_by
        - created_on
        - modified_on
        - instruction
        - is_deleted
        - parent
        - agent
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    AgentList_AgentType:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        created_by:
          type: string
          readOnly: true
          nullable: true
        modified_by:
          type: string
          readOnly: true
          nullable: true
        created_on:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        modified_on:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        name:
          type: string
          maxLength: 512
        description:
          type: string
          nullable: true
        parent:
          type: integer
          nullable: true
      required:
        - id
        - created_by
        - modified_by
        - created_on
        - modified_on
        - name
      x-apidog-orders:
        - id
        - created_by
        - modified_by
        - created_on
        - modified_on
        - name
        - description
        - parent
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    AgentList_User:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        email:
          type: string
          format: email
          title: Email address
          maxLength: 254
        first_name:
          type: string
          maxLength: 30
          nullable: true
        last_name:
          type: string
          maxLength: 30
          nullable: true
        organization:
          type: integer
          nullable: true
      required:
        - id
      x-apidog-orders:
        - id
        - email
        - first_name
        - last_name
        - organization
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    AgentListGet400ResponseSchema_V2:
      type: object
      properties:
        success:
          type: boolean
          default: false
        message:
          type: string
          default: Bad Request
        data:
          type: object
          additionalProperties:
            type: string
          default: {}
          x-apidog-orders: []
          properties: {}
          x-apidog-ignore-properties: []
      x-apidog-orders:
        - success
        - message
        - data
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    AgentListGet500ResponseSchema_V2:
      type: object
      properties:
        success:
          type: boolean
          default: false
        message:
          type: string
          default: Internal Server Error
        data:
          type: object
          additionalProperties:
            type: string
          default: {}
          x-apidog-orders: []
          properties: {}
          x-apidog-ignore-properties: []
      x-apidog-orders:
        - success
        - message
        - data
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
  securitySchemes:
    cookieAuth:
      type: apikey
      in: cookie
      name: sessionid
    oauth2:
      type: oauth2
      flows: {}
    APIKeyHeader:
      type: apikey
      in: header
      name: X-API-Key
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/login/access-token
    ejentoAuthKey:
      type: apikey
      in: header
      name: ejento-auth-key
      description: Server-to-server authentication key (EJENTO_SECRET / EJENTO_AUTH_KEY)
    Ocp-Apim-Subscription-Key:
      type: apikey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: Subscription key. Required on every endpoint.
    Authorization:
      type: bearer
      scheme: bearer
      description: >-
        Your access token, sent as `Authorization: Bearer <token>` alongside the
        subscription key.
    Combination:
      group:
        - id: 619278
        - id: 619279
      type: combination
servers:
  - url: https://{{your-server-name}}
    description: Prod Env
security: []

```