> ## Documentation Index > Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt > Use this file to discover all available pages before exploring further. # List Agents > Lists agents for the API key's company with pagination. Lists all agents (interview templates) for the API key's company with pagination support. ## Overview The list agents endpoint allows you to retrieve all available AI interview agents in your company. This is useful for finding existing agents before creating interviews, managing agent configurations, and auditing your agent library. ## Use Cases * **Find Existing Agents**: Locate agents before scheduling interviews * **Agent Management**: Review and audit all configured agents * **Bulk Operations**: Retrieve agents for bulk interview scheduling * **Agent Discovery**: Browse available agents by type or purpose ## Basic Usage ```javascript theme={null} // List all agents (first page, 20 items) GET /agents ``` ## With Pagination ```javascript theme={null} // Get specific page GET /agents?page=2&limit=50 // Response includes pagination metadata { "data": { "items": [...], "pagination": { "total": 25, "page": 2, "limit": 50, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": true } } } ``` ## Finding Agents for Interviews ```javascript theme={null} async function findAgentForInterview(interviewType) { const response = await fetch("https://api.instaview.sk/agents", { headers: { "Authorization": `Bearer ${apiKey}` }, }); const { data } = await response.json(); // Filter agents by interview type return data.items.filter((agent) => agent.type === interviewType); } // Find technical screening agents const technicalAgents = await findAgentForInterview("technical"); ``` ## Company Scoping All returned agents belong to your API key's company. ATS keys can filter by `companyId` to access agents from specific companies they manage. ## Related Resources Learn about agent configuration and best practices Create new interview agents Understand pagination best practices ## OpenAPI ````yaml GET /agents openapi: 3.0.0 info: title: InstaView API description: |- InstaView API Documentation ## Authentication All endpoints require API key authentication using Bearer token: ``` Authorization: Bearer sk_your_api_key_here ``` ## API Key Management The API Key module provides comprehensive key management for: - **Direct Client Keys**: Company-scoped keys for your applications - **ATS Partner Keys**: Resource-scoped keys for ATS integrations ### Key Features - HMAC-SHA256 hashing for API key storage - Configurable rate limiting - Comprehensive audit logging - Company-level isolation - Resource scoping for ATS partners version: 1.0.0 contact: {} servers: - url: https://api.instaview.sk description: Production API Gateway security: [] tags: [] paths: /agents: get: tags: - Agents summary: List agents description: Lists agents for the API key's company with pagination. operationId: PublicAgentsController_listAgents_v1 parameters: - name: page required: false in: query description: Page number (1-based) schema: minimum: 1 maximum: 10000 default: 1 example: 1 type: integer - name: limit required: false in: query description: Number of items per page schema: minimum: 1 maximum: 100 default: 20 example: 20 type: integer - name: companyId required: false in: query description: >- Filter agents by company ID. If omitted, defaults to the API key's company. schema: example: 123e4567-e89b-12d3-a456-426614174000 type: string format: uuid responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PublicListAgentsResponseDto' security: - bearer: [] components: schemas: PublicListAgentsResponseDto: type: object properties: data: description: Array of agents type: array items: $ref: '#/components/schemas/PublicAgentDto' total: type: number description: Total number of items example: 150 page: type: number description: Current page number example: 1 limit: type: number description: Number of items per page example: 20 totalPages: type: number description: Total number of pages example: 8 required: - data - total - page - limit - totalPages PublicAgentDto: type: object properties: id: type: string description: Agent ID format: uuid example: 123e4567-e89b-12d3-a456-426614174000 name: type: string description: Agent name example: Frontend Developer Interview type: type: string description: Type of the agent enum: - UNDEFINED - ONLINE - PHONE example: ONLINE focus: type: string description: >- Focus of the agent. GENERIC: For jobless interviews where candidates don't need job assignments. SCREENING: Initial candidate screening and assessment. OUTREACH: Candidate outreach and engagement. LANGUAGE_TEST: Language proficiency assessment. enum: - GENERIC - SCREENING - OUTREACH - LANGUAGE_TEST example: SCREENING questions: description: List of questions for the interview example: - What is your experience with React? type: array items: type: string instructions: type: string description: Additional instructions for the interview example: Focus on technical skills and previous project experience language: type: string description: Language of the interview enum: - UNDEFINED - EN - JA - ZH - DE - HI - FR - KO - PT - IT - ES - ID - NL - TR - FIL - PL - SV - BG - RO - AR - CS - EL - FI - HR - MS - SK - DA - TA - UK - RU - HU - 'NO' - VI example: EN duration: type: number description: Duration of the interview in minutes example: 30 voiceId: type: string description: Voice ID for the AI interview enum: - ALEX - PETER - MIRIAM - SUE - VIERA - CASANDRA - SILVIA - MICHAEL - LUKE - EMMA - SARAH - EVA companyId: type: string format: uuid description: Company ID that owns the agent example: 123e4567-e89b-12d3-a456-426614174000 metadata: type: object description: Custom metadata example: department: Sales cefrLevel: type: string description: CEFR level for language test agents enum: - A1 - A2 - B1 - B2 - C1 - C2 example: B1 backgroundSound: type: string description: >- Ambient background sound during calls (`OFFICE` or `OFF`). Null means no override is set and the default applies. enum: - 'OFF' - OFFICE example: OFFICE nullable: true createdAt: type: string description: Agent creation timestamp (UTC) example: '2025-11-20T10:30:00Z' format: date-time updatedAt: type: string description: Agent last update timestamp (UTC) example: '2025-11-20T10:30:00Z' format: date-time required: - id - name - type - focus - language - duration - createdAt - updatedAt securitySchemes: bearer: type: http scheme: bearer description: API key for authentication using Bearer scheme ````