Skip to navigation
Voice Agents APIAgents

Get agent by ID

View as Markdown

Returns the agent document merged with the resolved config of the active version under _resolvedConfig. Non-versioned fields (name, telephonyProductId, allowInboundCall, etc.) sit at the top level; versioned fields (prompt, tools, language, synthesizer, post-call analytics, …) are resolved from the target version and exposed under _resolvedConfig.

Previewing a draft or specific version

Pass ?draftId=<id> to resolve config from a specific draft instead of the active version. Pass ?versionId=<id> to resolve config from a specific published version. When either param is used, the response includes _configSource: "draft" | "version" | "active" indicating which config was resolved.

Notable resolved fields in _resolvedConfig:

  • prompt — active version’s single-prompt text
  • tools — configured tools on the resolved version
  • postCallAnalyticsConfig — disposition metrics + analytics model flags
  • modelName — LLM model name on the resolved version
  • defaultLanguage, supportedLanguages — active language config
  • firstMessage, globalPrompt — active messaging config
  • workflowGraph — full node graph for workflow_graph agents

To read prompt + tools alone, use GET /agent/{id}/workflow (deprecated for new integrations but still live). To inspect a specific non-active version, use GET /agent/{id}/versions/{versionId}.

400 — also used for “not found”: if the agent ID does not exist in the organization, the API returns 400 with errors: ["No agent found"] rather than 404.

Authentication

AuthorizationBearer

API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth.

Path parameters

idstringRequired>=1 character

Agent identifier (24-character hex id). Must be non-empty. An empty value resolves to GET /agent/, the list endpoint, and returns a different response shape.

Query parameters

draftIdstringOptional

Resolve _resolvedConfig from this draft instead of the active version. Sets _configSource to "draft" in the response.

versionIdstringOptional

Resolve _resolvedConfig from this published version instead of the active version. Sets _configSource to "version" in the response.

Response

Successful response
statusbooleanOptional
dataobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
500
Internal Server Error