List agents
curl --request GET \
--url https://api.instaview.sk/agents \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.instaview.sk/agents"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.instaview.sk/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.instaview.sk/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.instaview.sk/agents"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.instaview.sk/agents")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instaview.sk/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Frontend Developer Interview",
"type": "ONLINE",
"focus": "SCREENING",
"language": "EN",
"duration": 30,
"createdAt": "2025-11-20T10:30:00Z",
"updatedAt": "2025-11-20T10:30:00Z",
"questions": [
"What is your experience with React?"
],
"instructions": "Focus on technical skills and previous project experience",
"voiceId": "ALEX",
"companyId": "123e4567-e89b-12d3-a456-426614174000",
"metadata": {
"department": "Sales"
},
"cefrLevel": "B1",
"backgroundSound": "OFFICE",
"flow": {
"firstMessage": {
"type": "first_message",
"text": "Hi {{contact.firstName}}, do you have two minutes?",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"sections": [
{
"type": "sequential",
"prompt": "Introduce yourself and explain why you are calling.",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
}
],
"lastMessage": {
"type": "last_message",
"text": "Thanks for your time — have a great day!",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"schemaVersion": "1.0.0"
},
"guardrails": {
"rules": [
"Never quote a price",
"Never promise a delivery date"
]
},
"contextConfig": {
"role": "an account executive for Acme",
"communicationStyle": "concise and direct",
"callToAction": "book a 30-minute demo",
"useContactContext": true
},
"analyticsConfig": {
"extractionTargets": [
{
"label": "Budget confirmed",
"type": "bool",
"key": "budget_confirmed",
"enumValues": [
"hot",
"warm",
"cold"
],
"ideal": "A confirmed budget of at least 10k",
"importance": "PREFERRED",
"weight": 40
}
],
"scoringCriteria": [
{
"label": "Handled objections",
"description": "Acknowledged the objection and answered it with a concrete example",
"key": "handled_objections",
"importance": "PREFERRED",
"weight": 40
}
],
"outcomes": [
{
"label": "Meeting booked",
"description": "The contact agreed to a specific date and time",
"key": "meeting_booked"
}
],
"outputTags": [
{
"label": "Needs follow-up",
"key": "needs_followup",
"description": "The contact asked to be called back"
}
],
"capture": {
"recording": true,
"transcript": true,
"summary": true,
"qa": true,
"evaluation": true,
"sentiment": true
}
},
"callConfig": {
"retryPolicy": {
"maxAttempts": 3
},
"callWindow": {
"mode": "custom",
"days": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"start": "09:00",
"end": "18:00",
"timezoneAnchor": {
"mode": "contact",
"timezone": "Europe/Bratislava",
"fallbackTimezone": "Europe/Bratislava"
}
}
},
"overrides": {
"companyName": "Acme Manufacturing",
"companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
}
}
],
"total": 150,
"page": 1,
"limit": 20,
"totalPages": 8
}Agents
List Agents
Lists agents for the API key’s company with pagination.
GET
/
agents
List agents
curl --request GET \
--url https://api.instaview.sk/agents \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.instaview.sk/agents"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.instaview.sk/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.instaview.sk/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.instaview.sk/agents"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.instaview.sk/agents")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instaview.sk/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Frontend Developer Interview",
"type": "ONLINE",
"focus": "SCREENING",
"language": "EN",
"duration": 30,
"createdAt": "2025-11-20T10:30:00Z",
"updatedAt": "2025-11-20T10:30:00Z",
"questions": [
"What is your experience with React?"
],
"instructions": "Focus on technical skills and previous project experience",
"voiceId": "ALEX",
"companyId": "123e4567-e89b-12d3-a456-426614174000",
"metadata": {
"department": "Sales"
},
"cefrLevel": "B1",
"backgroundSound": "OFFICE",
"flow": {
"firstMessage": {
"type": "first_message",
"text": "Hi {{contact.firstName}}, do you have two minutes?",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"sections": [
{
"type": "sequential",
"prompt": "Introduce yourself and explain why you are calling.",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
}
],
"lastMessage": {
"type": "last_message",
"text": "Thanks for your time — have a great day!",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"schemaVersion": "1.0.0"
},
"guardrails": {
"rules": [
"Never quote a price",
"Never promise a delivery date"
]
},
"contextConfig": {
"role": "an account executive for Acme",
"communicationStyle": "concise and direct",
"callToAction": "book a 30-minute demo",
"useContactContext": true
},
"analyticsConfig": {
"extractionTargets": [
{
"label": "Budget confirmed",
"type": "bool",
"key": "budget_confirmed",
"enumValues": [
"hot",
"warm",
"cold"
],
"ideal": "A confirmed budget of at least 10k",
"importance": "PREFERRED",
"weight": 40
}
],
"scoringCriteria": [
{
"label": "Handled objections",
"description": "Acknowledged the objection and answered it with a concrete example",
"key": "handled_objections",
"importance": "PREFERRED",
"weight": 40
}
],
"outcomes": [
{
"label": "Meeting booked",
"description": "The contact agreed to a specific date and time",
"key": "meeting_booked"
}
],
"outputTags": [
{
"label": "Needs follow-up",
"key": "needs_followup",
"description": "The contact asked to be called back"
}
],
"capture": {
"recording": true,
"transcript": true,
"summary": true,
"qa": true,
"evaluation": true,
"sentiment": true
}
},
"callConfig": {
"retryPolicy": {
"maxAttempts": 3
},
"callWindow": {
"mode": "custom",
"days": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"start": "09:00",
"end": "18:00",
"timezoneAnchor": {
"mode": "contact",
"timezone": "Europe/Bratislava",
"fallbackTimezone": "Europe/Bratislava"
}
}
},
"overrides": {
"companyName": "Acme Manufacturing",
"companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
}
}
],
"total": 150,
"page": 1,
"limit": 20,
"totalPages": 8
}Lists the agents belonging to the API key’s company, with pagination.
Overview
Returns every agent available to your company — useful for picking one before creating a conversation, and for auditing what you have.Use Cases
- Find Existing Agents: Locate an agent before scheduling a call
- Agent Management: Review and audit all configured agents
- Bulk Operations: Retrieve agents for scheduling calls in bulk
- Agent Discovery: Browse available agents by type or purpose
Basic Usage
// List all agents (first page, 20 items)
GET /agents
With Pagination
// Get specific page
GET /agents?page=2&limit=50
// Response includes pagination metadata
{
"data": [...],
"total": 25,
"page": 2,
"limit": 50,
"totalPages": 1
}
Finding an Agent by Type
The endpoint is paginated, so walk every page before filtering — a company with more agents than one page holds would otherwise lose the matches sitting on later pages.async function findAgentByType(agentType) {
const matches = [];
let page = 1;
let totalPages = 1;
do {
const response = await fetch(
`https://api.instaview.sk/agents?page=${page}&limit=50`,
{
headers: { Authorization: `Bearer ${apiKey}` },
// Without a deadline a stalled request hangs this loop indefinitely.
signal: AbortSignal.timeout(10_000),
},
);
if (!response.ok) {
throw new Error(
`Listing agents failed: ${response.status} ${response.statusText}`,
);
}
const body = await response.json();
totalPages = body.totalPages;
matches.push(...body.data.filter((agent) => agent.type === agentType));
page += 1;
} while (page <= totalPages);
return matches;
}
// Find ONLINE agents
const onlineAgents = await findAgentByType("ONLINE");
Company Scoping
All returned agents belong to your API key’s company. ATS keys can filter bycompanyId to access agents from specific companies they manage.
Related Resources
Agents Resource Guide
Learn about agent configuration and best practices
Create Agent
Create a new agent
Pagination Guide
Understand pagination best practices
Authorizations
API key for authentication using Bearer scheme
Query Parameters
Page number (1-based)
Required range:
1 <= x <= 10000Example:
1
Number of items per page
Required range:
1 <= x <= 100Example:
20
Filter agents by company ID. If omitted, defaults to the API key's company.
Example:
"123e4567-e89b-12d3-a456-426614174000"