HighLevel: List Agents — voice Ai get Agents
HighLevel voiceAi.getAgents: arguments, response, policy and SDK examples.
← Voice AI operations · Get started
Operation gohighlevel.get_agents
Provider route: GET /voice-ai/agents. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/gohighlevel with npm, or alter-sdk-gohighlevel with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { HighLevelIntegration } from "@alter-ai/gohighlevel";
async function execute(input: Parameters<HighLevelIntegration["voiceAi"]["getAgents"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new HighLevelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.voiceAi.getAgents(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_gohighlevel import HighLevelIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = HighLevelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.voice_ai.get_agents(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
query | object | Required within parent | Additional keys: not allowed |
query.page | number | Optional | Default: 1 Maximum: 5000 Minimum: 1 |
query.pageSize | number | Optional | Default: 10 Maximum: 50 Minimum: 1 |
query.locationId | string | Required within parent | |
query.query | string | Optional |
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand List Agents — voice Ai get Agents — response body |
Referenced models: List Agents — voice Ai get Agents — response body
Schemas
Section titled “Schemas”13 more schemas are linked from the tables above, on the schema pages.
List Agents — voice Ai get Agents — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
agents | array | Required within parent | |
agents[] | Model | Each item | Expand List Agents — voice Ai get Agents — response body — agents item |
page | JSON | Required within parent | |
page (anyOf 1) | number | Alternative | Page number starting from 1 |
page (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
pageSize | JSON | Required within parent | |
pageSize (anyOf 1) | number | Alternative | Number of items per page |
pageSize (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
total | JSON | Required within parent | |
total (anyOf 1) | number | Alternative | Total number of items |
total (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Referenced models: List Agents — voice Ai get Agents — response body — agents item
List Agents — voice Ai get Agents — response body — agents item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
actions | array | Required within parent | Raw actions configured for this agent with complete actionParameters structure |
actions[] | Model | Each item | Expand List Agents — voice Ai get Agents — response body — agents item actions item |
agentName | string | Required within parent | Display name of the voice AI agent |
agentPrompt | string | Required within parent | Custom instructions defining the agent's behavior |
agentWorkingHours | array | Optional | Time intervals when the agent accepts calls, organized by day of week |
agentWorkingHours[] | Model | Each item | Expand Patch Agent — response body — agent Working Hours item |
businessName | string | Required within parent | Name of the business this agent represents |
callEndWorkflowIds | array | Optional | Array of workflow IDs triggered automatically when calls end |
callEndWorkflowIds[] | string | Each item | |
id | string | Required within parent | Unique identifier for the created agent |
inboundNumber | string | Optional | Phone number for receiving inbound calls |
isAgentAsBackupDisabled | boolean | Required within parent | Indicates whether this agent is excluded from backup scenarios |
language | string | Required within parent | Language code for the agent's speech and understanding |
locationId | string | Required within parent | Unique identifier for the location where this agent operates |
maxCallDuration | JSON | Required within parent | |
maxCallDuration (anyOf 1) | number | Alternative | Maximum call duration in seconds, between 180-900 Maximum: 900 Minimum: 180 |
maxCallDuration (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
numberPoolId | string | Optional | Identifier for the number pool managing this agent's phone allocation |
patienceLevel | string | Required within parent | Current tolerance level for caller response delays |
reminderAfterIdleTimeSeconds | JSON | Required within parent | |
reminderAfterIdleTimeSeconds (anyOf 1) | number | Alternative | Seconds to wait before sending idle reminders, between 1-20 Maximum: 20 Minimum: 1 |
reminderAfterIdleTimeSeconds (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
sendPostCallNotificationTo | JSON | Optional | Current post-call notification settings including recipient configuration |
sendPostCallNotificationTo (allOf 1) | Model | All variants apply | Expand Patch Agent — response body — send Post Call Notification To admins, all Users, contact Assigned User, custom Emails, specific Users |
sendUserIdleReminders | boolean | Required within parent | Indicates whether automatic idle reminders are enabled |
timezone | string | Required within parent | IANA timezone identifier for working hours and scheduling |
translation | JSON | Optional | Current language translation settings including enablement status and target language |
translation (allOf 1) | Model | All variants apply | Expand Patch Agent — response body — translation enabled, language |
voiceId | string | Required within parent | Identifier for the speech synthesis voice being used |
welcomeMessage | string | Required within parent | Greeting message spoken when the agent answers calls |
Referenced models: List Agents — voice Ai get Agents — response body — agents item actions item, Patch Agent — response body — agent Working Hours item, Patch Agent — response body — send Post Call Notification To admins, all Users, contact Assigned User, custom Emails, specific Users, Patch Agent — response body — translation enabled, language
List Agents — voice Ai get Agents — response body — agents item actions item
Referenced models: List Agents — voice Ai get Agents — response body — agents item actions item action Parameters contact Field Id, description, examples, overwrite Existing Value, List Agents — voice Ai get Agents — response body — agents item actions item action Parameters knowledge Base Id, trigger Prompt, List Agents — voice Ai get Agents — response body — agents item actions item action Parameters calendar Id, days Of Offering Dates, hours Between Slots, slots Per Day, List Agents — voiceAi.getAgents — response body — agents / item / actions / item / actionParameters / transferToType: number, List Agents — voice Ai get Agents — response body — agents item actions item action Parameters api Details, selected Paths, trigger Message, trigger Prompt, List Agents — voice Ai get Agents — response body — agents item actions item action Parameters message Body, trigger Message, trigger Prompt, List Agents — voice Ai get Agents — response body — agents item actions item action Parameters trigger Message, trigger Prompt, workflow Id
Patch Agent — response body — agent Working Hours item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
dayOfTheWeek | JSON | Required within parent | |
dayOfTheWeek (anyOf 1) | number | Alternative | Day of the week for this working hours configuration (Monday=1 to Sunday=7) Known values: 1, 2, 3, 4, 5, 6, 7 |
dayOfTheWeek (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
intervals | array | Required within parent | Array of time intervals when the agent is available on this day |
intervals[] | Model | Each item | Expand Patch Agent — response body — agent Working Hours item intervals item |
Referenced models: Patch Agent — response body — agent Working Hours item intervals item
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: gohighlevel.get_agents. Catalog operation: get-agents. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["voice-ai-agents.readonly"]
Pinned headers: {"Version": "v3"}