Skip to main content
GET
Get agent by ID
Retrieves a single agent by ID, with its full configuration, questions and evaluation criteria.

Overview

Returns everything held about one agent: its name, description, voice settings, type, questions and evaluation criteria — useful for checking a configuration before you point a conversation at it.

Use Cases

  • Review Agent Configuration: Inspect an agent before scheduling a call with it
  • Validate Agent Details: Verify questions and evaluation criteria
  • Agent Auditing: Review agent configurations for compliance
  • Configuration Reference: Get agent details for documentation or reporting

Response Data

The response includes all agent configuration:
The example above is a template agent. A custom agent additionally returns its flow, guardrails, contextConfig, analyticsConfig and callConfig — the last being how persistently and when it calls, described under Retries and calling hours. An agent created before calling windows were configurable reports a callWindow.mode of business_hours, a legacy preset meaning Mon–Fri 08:00–20:00 in the contact’s own timezone; template agents carry no callConfig at all.

When to Use

Use this endpoint when you need complete agent details. For listing multiple agents, use the List Agents endpoint instead.

Company Isolation

You can only access agents that belong to your API key’s company. Attempting to access an agent from another company will result in a 403 Forbidden error.

Error Scenarios

  • 404 Not Found: Agent doesn’t exist or has been deleted
  • 403 Forbidden: Agent belongs to a different company

Agents Resource Guide

Learn about agent configuration

Update Agent

Modify agent configuration

List Agents

Browse all available agents

Authorizations

Authorization
string
header
required

API key for authentication using Bearer scheme

Path Parameters

id
string<uuid>
required

Query Parameters

companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Response

id
string<uuid>
required

Agent ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

name
string
required

Agent name

Example:

"Frontend Developer Interview"

type
enum<string>
required

Type of the agent

Available options:
UNDEFINED,
ONLINE,
PHONE
Example:

"ONLINE"

focus
enum<string>
required

Focus of the agent. GENERIC: job-optional, for a conversation that is not about a particular job. SCREENING: a hiring screen against a job's requirements. OUTREACH: a first call to gauge interest. LANGUAGE_TEST: language proficiency.

Available options:
GENERIC,
SCREENING,
OUTREACH,
LANGUAGE_TEST
Example:

"SCREENING"

language
enum<string>
required

Language of the conversation

Available options:
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
number
required

Duration of the conversation in minutes

Example:

30

createdAt
string<date-time>
required

Agent creation timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

updatedAt
string<date-time>
required

Agent last update timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

questions
string[]

List of questions for the conversation

Example:
instructions
string

Additional instructions for the conversation

Example:

"Focus on technical skills and previous project experience"

voiceId
enum<string>

Voice ID the agent speaks with

Available options:
ALEX,
PETER,
MIRIAM,
SUE,
VIERA,
CASANDRA,
SILVIA,
MICHAEL,
LUKE,
EMMA,
SARAH,
EVA
companyId
string<uuid>

Company ID that owns the agent

Example:

"123e4567-e89b-12d3-a456-426614174000"

metadata
object

Custom metadata

Example:
cefrLevel
enum<string>

CEFR level for language test agents

Available options:
A1,
A2,
B1,
B2,
C1,
C2
Example:

"B1"

backgroundSound
enum<string> | null

Ambient background sound during calls (OFFICE or OFF). Null means no override is set and the default applies.

Available options:
OFF,
OFFICE
Example:

"OFFICE"

flow
object | null

Conversation flow graph, as designed. Null on a template agent.

guardrails
object | null

Rules the agent must obey during the call. Custom agents only; null on a template agent.

contextConfig
object | null

Who the agent is and what the call is about. Custom agents only; null on a template agent.

analyticsConfig
object | null

What the agent extracts, scores, decides and labels after every call. Custom agents only — null on a template agent. Per-question scoring is folded back onto the flow's looping questions rather than returned as an id-keyed map — the same form the write accepts.

callConfig
object

How persistently and when the agent calls. Custom agents only. An agent created before calling windows were configurable reports a callWindow.mode of business_hours.

overrides
object | null

Who this agent says it is on a call, when that is not the company your API key belongs to. Null when it speaks as your own company.