List agents

Return every active agent on a rooftop, with its phone number. The "Assign Number" task uses this list to find the agent for the current tab and to check whether it already has a number.

GEThttps://api.spyne.ai/conversation/agents/team/{teamId}/onboarded-agents

AuthBearer token (console user)Rate limitNot documentedProcessingSynchronous, database reads

All active, non-demo agents are returned, whether or not they are live. isOnboarded shows whether each agent is live. Each item has the same fields as Get an agent, plus agent type, use case, call type and isOnboarded, and the agent's active phone number when one exists. Nothing is stored.

Auth: Bearer token of a signed-in user, checked with the identity service. The route does not check that the token belongs to this rooftop. Rate limit: not documented. Processing: synchronous, database reads.

Before you call it

You need the rooftop teamId.

Path parameters

Requiredalways send

Parameter	Type	Required	Description
`teamId`	string	Required	Rooftop.

Sample request

curl "https://api.spyne.ai/conversation/agents/team/<teamId>/onboarded-agents" \
  -H "Authorization: Bearer YOUR_TOKEN"

import requests

res = requests.get(
    "https://api.spyne.ai/conversation/agents/team/<teamId>/onboarded-agents",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
)
print(res.status_code, res.json())

const res = await fetch('https://api.spyne.ai/conversation/agents/team/<teamId>/onboarded-agents', {
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
});
console.log(res.status, await res.json());

Sample response

[
  {
    "teamAgentMappingId": "<teamAgentMappingId>",
    "agentTypeId": "<agentTypeId>",
    "name": "Ava",
    "gender": "female",
    "avatarId": "<avatarId>",
    "imageUrl": "https://example.com/avatar.png",
    "agentType": "sales",
    "agentUseCase": "<agentUseCase>",
    "agentCallType": "inbound",
    "countryCode": "US",
    "nationality": "American",
    "city": "LA",
    "firstMessage": "Thanks for calling Example Motors, this is Ava. How can I help?",
    "voicemailMessage": "",
    "endCallMessage": "",
    "afterHoursMessage": "",
    "partiallyOpenMessage": "",
    "transferMode": "seamless",
    "transferModeRule": "",
    "audioUrl": "",
    "isOnboarded": false,
    "supportedLanguages": [{ "languageName": "english", "languageCode": "en" }],
    "capabilities": [],
    "phoneNumber": "+1XXXXXXXXXX",
    "tts": { "provider": "elevenlabs", "voiceId": "<voiceId>", "supportedLanguages": ["en"] },
    "executionMode": "single_agent",
    "assertiveness": "low",
    "ambientSound": { "type": "office", "volume": 0.6 }
  }
]

{
  "statusCode": 400,
  "message": "Failed to retrieve onboarded agents",
  "errorCode": "BAD_REQUEST",
  "timestamp": "2026-10-12T10:00:00.000Z",
  "requestId": "req_1760263200000_abc123xyz",
  "context": {},
  "path": "/conversation/agents/team/<teamId>/onboarded-agents",
  "method": "GET"
}

A 401 has the same shape as on Browse the voice library. A rooftop with no agents returns 200 with [].

Response parameters (200)

The body is an array. Each item has these fields.

Parameter	Type	Description
`[].teamAgentMappingId`	string	Agent id. Send it to Assign a phone number.
`[].agentType`	string	For example `sales`, `service`, `acquisition` or `receptionist`.
`[].agentCallType`	string	`inbound` or `outbound`.
`[].agentUseCase`	string	Agent use case.
`[].isOnboarded`	boolean	Whether the agent is live.
`[].phoneNumber`	string	Active E.164 number, if any. Missing when none is attached.
`[].supportedLanguages`	array	Languages on the record, or one derived from the transcriber setting.
Other fields	mixed	Same as Get an agent, without `voiceConfig`.

Errors

Status	Reason	When it happens
`400`	Failed to retrieve onboarded agents	A database read failed.
`401`	Authentication failed	Missing or rejected token.

What happens next

Find the agent whose agentType and agentCallType match the tab. If phoneNumber is set, the console UI shows it and does not buy another. If not, call Assign a phone number with its teamAgentMappingId.