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

# List counsellors

> The people in your account who can take human calls (active users with a Counsellor or Admin role), whether each can be called now, and why not. Phone numbers are never returned.

Scope: `human_calls:read`.



## OpenAPI

````yaml /api-reference/openapi.json get /counsellors
openapi: 3.1.0
info:
  title: Telleo API
  version: 1.2.0
  description: >-
    Start AI phone calls, or connect your counsellors to contacts, from your own
    systems and get each call's outcome back.
servers:
  - url: https://api.telleo.ai/v1
security:
  - ApiKey: []
tags:
  - name: Calls
  - name: Batches
  - name: Agents
  - name: Human calls
  - name: Credits
  - name: Webhook
paths:
  /counsellors:
    get:
      tags:
        - Human calls
      summary: List counsellors
      description: >-
        The people in your account who can take human calls (active users with a
        Counsellor or Admin role), whether each can be called now, and why not.
        Phone numbers are never returned.


        Scope: `human_calls:read`.
      operationId: listCounsellors
      responses:
        '200':
          description: Your counsellors.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CounsellorList'
        '401':
          description: The key is missing, unknown, revoked or expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_api_key:
                  value:
                    error:
                      code: missing_api_key
                      message: Send your API key in the X-API-Key header.
                      request_id: req_8f2c1a7e
                invalid_api_key:
                  value:
                    error:
                      code: invalid_api_key
                      message: This API key is not valid.
                      request_id: req_8f2c1a7e
        '403':
          description: >-
            The key lacks the human-call scope this request needs. Keys only
            have human_calls:read / human_calls:write when created with them.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficient_scope:
                  value:
                    error:
                      code: insufficient_scope
                      message: This API key does not have the human_calls:write scope.
                      request_id: req_8f2c1a7e
        '429':
          description: Too many requests for this key.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error:
                      code: rate_limited
                      message: Too many requests. Retry after 12 seconds.
                      request_id: req_8f2c1a7e
        '503':
          description: Your user directory could not be read for a moment.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                temporarily_unavailable:
                  value:
                    error:
                      code: temporarily_unavailable
                      message: >-
                        Could not load this account's counsellors right now.
                        Retry shortly.
                      request_id: req_8f2c1a7e
components:
  headers:
    RequestId:
      schema:
        type: string
      description: Unique id of this request. Quote it to support.
  schemas:
    CounsellorList:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Counsellor'
        has_more:
          type: boolean
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable code. Branch on this, not on the message.
              example: invalid_request
            message:
              type: string
              description: A sentence you can log or show to an operator.
            request_id:
              type: string
              description: Quote this when you contact support.
            details:
              type: object
              additionalProperties: true
              description: >-
                Extra context, e.g. `errors: [{field, message}]` for validation
                errors or `call_id` for conflicts.
    Counsellor:
      type: object
      properties:
        id:
          type: string
          description: Use as `counsellor_id` on `POST /human-calls`.
        object:
          type: string
          const: counsellor
        name:
          type: string
        email:
          type:
            - string
            - 'null'
        roles:
          type: array
          items:
            type: string
          example:
            - COUNSELLOR
        can_call:
          type: boolean
          description: >-
            Whether this person can take a human call right now on your calling
            provider.
        blocked_reason:
          type:
            - string
            - 'null'
          description: >-
            Why `can_call` is false, e.g. no mobile number on their profile
            (Vacademy Voice, Exotel) or no Airtel extension mapped.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your AI calling API key (`vak_call_…`). `Authorization: Bearer <key>`
        also works.

````

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