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

# List Agents

> Retrieve a paginated list of the agents your organization operates, newest first  
Each agent includes its DID, its status and how many keys it holds  
Use pageIndex and pageSize to page through the results



## OpenAPI

````yaml /versions/2026-10-16.yaml get /agents
openapi: 3.1.0
info:
  title: Humanos API
  description: Humanos API
  version: '1.0'
  contact: {}
servers:
  - url: https://api.humanos.tech
security: []
tags:
  - name: humanosApp
    description: ''
paths:
  /agents:
    get:
      tags:
        - Agents
      summary: List Agents
      description: >-
        Retrieve a paginated list of the agents your organization operates,
        newest first  

        Each agent includes its DID, its status and how many keys it holds  

        Use pageIndex and pageSize to page through the results
      operationId: agents_list
      parameters:
        - name: pageIndex
          required: false
          in: query
          description: Zero-based page index. `0` returns the first page.
          schema:
            minimum: 0
            default: 0
            example: 0
            type: number
        - name: pageSize
          required: false
          in: query
          description: Number of items per page
          schema:
            minimum: 5
            maximum: 100
            default: 10
            example: 10
            type: number
        - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: >-
            Returns a page of the organization's agents plus the total number of
            pages available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentsEntity'
        '400':
          description: >-
            Invalid query parameters, e.g. a negative pageIndex or a pageSize
            outside 5-100.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 400
                  message:
                    type: string
                    example: pageIndex must not be less than 0
                  error:
                    type: string
                    example: Bad Request
components:
  parameters:
    ApiVersion:
      name: API-Version
      in: header
      required: false
      schema:
        type: string
        pattern: ^\d{4}-\d{2}-\d{2}$
        example: '2026-10-16'
      description: >-
        Pin request, response, and webhook shapes to a specific dated API
        version (YYYY-MM-DD). Omit to use the version pinned to your API key
        (set when the key is created; new keys default to the latest version).
        New integrations should target the latest version.
  schemas:
    AgentsEntity:
      type: object
      properties:
        data:
          description: The organization's agents on this page, newest first.
          type: array
          items:
            $ref: '#/components/schemas/AgentEntity'
        totalPages:
          type: number
          description: >-
            Total number of pages available based on the page size and total
            count
          example: 1
      required:
        - data
        - totalPages
    AgentEntity:
      type: object
      properties:
        did:
          type: string
          description: The agent's DID.
          example: did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35
        status:
          type: string
          description: 'The actor''s status (v0.3 §4): active, suspended or retired.'
          enum:
            - active
            - suspended
            - retired
          example: active
        createdAt:
          format: date-time
          type: string
          description: When the agent was registered.
          example: '2026-09-02T10:15:00.000Z'
        keyCount:
          type: number
          description: Number of keys on the actor, including rotated and revoked ones.
          example: 1
      required:
        - did
        - status
        - createdAt
        - keyCount

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.