---
title: "Get agent by ID"
method: GET
path: "/agent/{id}"
tags: ["Agents"]
---

# Get agent by ID

`GET /agent/{id}`

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.

## Path parameters

- `id` string, required — Agent identifier (Mongo ObjectId string). Must be non-empty. An empty `id` would resolve to `GET /agent/`, which is the list endpoint — Fern adds the `minLength: 1` guard so the generated SDK raises locally rather than silently calling the wrong route.

## Query parameters

- `draftId` string
- `versionId` string

## Response `200`

Successful response

- object
  - `status` boolean
  - `data` AgentDTO
    - `_id` string — The ID of the agent
    - `name` string — The name of the agent
    - `description` string — The description of the agent
    - `backgroundSound` '' | 'office' | 'cafe' | 'call_center' | 'static' — Ambient background sound during calls. Options: '' (none), 'office', 'cafe', 'call_center', 'static'.
    - `organization` string — The organization ID of the agent
    - `workflowId` string — The workflow ID of the agent
    - `workflowType` 'workflow_graph' | 'single_prompt' — The type of workflow configuration. workflow_graph uses a node-based visual workflow, single_prompt uses a simple prompt-based configuration.
    - `createdBy` string — The user ID of the user who created the agent
    - `globalKnowledgeBaseId` string — The global knowledge base ID of the agent
    - `language` object — The language configuration of the agent
      - `default` 'en' | 'hi' | 'mr' | 'gu' | 'ta' | 'es' | 'north_indic' | 'bn' | 'or' — The default language of the agent
      - `switching` object — Language switching configuration for the agent
        - `isEnabled` boolean — Whether language switching is enabled for the agent
        - `minWordsForDetection` number — Minimum number of words required for language detection
        - `strongSignalThreshold` number — Threshold for strong language signal detection
        - `weakSignalThreshold` number — Threshold for weak language signal detection
        - `minConsecutiveForWeakThresholdSwitch` number — Minimum consecutive detections required for weak threshold language switch
      - `supported` string[] — The supported languages of the agent
    - `synthesizer` object — The synthesizer (TTS) configuration of the agent
      - `voiceConfig` object — The voice configuration of the synthesizer
        - `model` 'waves_lightning_v3_1' | 'gpt-realtime' | 'gpt-realtime-mini' — The TTS model of the synthesizer. Use `waves_lightning_v3_1` for the recommended Waves voice path (default), or `gpt-realtime` / `gpt-realtime-mini` for OpenAI realtime models.
        - `voiceId` string — The voice ID of the synthesizer.
        - `gender` 'male' | 'female'
      - `speed` number — The speed of the synthesizer
      - `consistency` number — The consistency of the synthesizer
      - `similarity` number — The similarity of the synthesizer
      - `enhancement` number — The enhancement of the synthesizer
      - `sampleRate` number — The audio sample rate used by the synthesizer
    - `slmModel` 'electron' | 'electron-kogta' | 'electron-kogta-v2' | 'gpt-4o' | 'gpt-4.1' | 'gpt-5.2' | 'gpt-realtime' | 'gpt-realtime-mini' — The LLM model to use for the agent. LLM model will be used to generate the response and take decisions based on the user's query.
    - `defaultVariables` object — The default variables to use for the agent. These variables will be used if no variables are provided when initiating a conversation with the agent.
    - `preCallAPI` object — Configuration for an API call to be made before the call starts. The response variables can be injected into the agent's prompt.
      - `isEnabled` boolean — Whether the pre-call API is enabled.
      - `url` string, uri, required — The URL of the API endpoint to call.
      - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', required — The HTTP method to use for the API call.
      - `headers` object — Optional HTTP headers to include in the request.
      - `body` object — Optional request body for POST/PUT/PATCH requests.
      - `timeout` integer — Timeout in seconds for the API call.
      - `queryParams` object — Optional query parameters to include in the request URL.
      - `responseVariables` object[] — List of variables to extract from the API response using JSON path expressions.
        - `variableName` string, required — The name of the variable to inject into the agent prompt.
        - `jsonPath` string, required — JSON path expression to extract the value from the API response.
    - `createdAt` string, date-time — The date and time when the agent was created
    - `updatedAt` string, date-time — The date and time when the agent was last updated
    - `avatarUrl` string — URL of the agent's avatar image
    - `firstMessage` string — The opening message spoken by the agent at the start of a call
    - `allowInterruptions` boolean — Whether the agent can be interrupted mid-speech by the caller
    - `waitForUserToSpeakFirst` boolean — When true, the agent waits for the caller to speak before responding
    - `totalCalls` number — Total number of calls made with this agent
    - `transcriberType` string — The speech-to-text engine used for transcription
    - `globalPrompt` string — A global system prompt prepended to all agent interactions
    - `archived` boolean — Whether the agent has been archived. Archived agents are excluded from default listings.
    - `archivedAt` string, date-time — The date and time when the agent was archived
    - `activeVersionId` string — ID of the currently-active published version. Matches `versionId`.
    - `versionId` string — Alias for `activeVersionId`.
    - `allowInboundCall` boolean — Whether the agent accepts inbound calls.
    - `phoneNumber` string[] — Phone numbers attached to this agent (E.164 strings). Only present when the agent has been linked to one or more telephony products.
    - `visibleToEveryone` boolean — Whether the agent is visible to all members of the organization (vs. only the creator).
    - `speechFormatting` boolean — Apply LLM-side speech formatting (e.g. expanding "$100" to "one hundred dollars") before passing text to the synthesizer. Boolean; no default — when unset the platform applies the per-organization default.
    - `muteUserUntilFirstBotResponse` boolean — When true, the user microphone is muted until the agent has spoken its first response.
    - `interruptionBackoffTimer` number — Seconds to wait after an interruption before the agent resumes speaking.
    - `enableStyleGuide` boolean — Whether to apply the platform's style-guide post-processing on agent responses.
    - `callDispositionConfig` string — Free-form prompt used for call disposition classification (separate from `postCallAnalyticsConfig.dispositionMetrics`).
    - `voiceMailDetectionConfig` object — Voicemail detection settings.
      - `enabled` boolean
      - `endText` string — Text spoken before the call is terminated when voicemail is detected.
    - `smartTurnConfig` object — Smart end-of-turn detection settings.
      - `isEnabled` boolean
      - `waitTimeInSecs` number
    - `voiceDetectionConfig` object — VAD (voice activity detection) tuning.
      - `confidence` number
      - `minVolume` number
      - `triggerTimeInSecs` number
      - `releaseTimeInSecs` number
    - `denoisingConfig` object — Audio denoising settings.
      - `isEnabled` boolean
    - `redactionConfig` object — PII/PCI redaction settings applied to transcripts.
      - `isEnabled` boolean
    - `pronunciationDicts` object[] — Custom pronunciation dictionary applied before synthesis.
      - `word` string, required
      - `pronunciation` string, required
    - `llmIdleTimeoutConfig` object — Per-channel idle timeouts (seconds) after which the LLM is nudged when the user stops speaking. `maxRetries` bounds how many nudges before the call ends.
      - `chatTimeoutTimeInSecs` number
      - `webcallTimeoutTimeInSecs` number
      - `telephonyTimeoutTimeInSecs` number
      - `maxRetries` number
    - `sessionTimeoutConfig` object — Maximum session duration before the call is automatically ended.
      - `timeoutTimeInSecs` number
    - `timezone` object — Agent timezone — used for time-of-day-sensitive prompts and analytics bucketing.
      - `label` string
      - `offset` number
    - `postCallAnalyticsConfig` PostCallAnalyticsConfig — Per-agent post-call analytics configuration. Evaluated after each call ends and surfaced in call logs under the `postCallAnalytics` field.
      - `dispositionMetrics` DispositionMetric[] — Structured metrics extracted from each completed call.
        - `identifier` string, required — Stable machine identifier. Lowercase letters, digits, and underscores only.
        - `dispositionMetricPrompt` string, required — Natural-language question evaluated against the transcript after the call ends.
        - `dispositionMetricType` 'STRING' | 'BOOLEAN' | 'INTEGER' | 'ENUM' | 'DATETIME', required — Data type returned by the metric.
        - `choices` string[] — Required when `dispositionMetricType = ENUM`. Allowed values.
      - `successMetrics` object[] — **Deprecated** — will be removed in a future version. Use `dispositionMetrics` instead. Kept here because the backend still accepts it on writes and returns it on reads.
        - `identifier` string, required
        - `successMetricPrompt` string, required
        - `successMetricType` 'NUMERIC_SCALE' | 'PERCENTAGE_SCALE' | 'PASS_FAIL' | 'DESCRIPTIVE_SCALE', required
      - `summaryPrompt` string — **Deprecated** — no longer used in post-call analysis and will be removed in a future version. Kept here because the backend still accepts it on writes and returns it on reads.
      - `useInternalAnalyticsModel` boolean — Use the internal analytics model. When false, falls back to the agent's own LLM.
      - `useReasoningModel` boolean — Route analytics evaluation through the reasoning model for higher-quality results at a latency/cost tradeoff.
    - `widgetConfig` object — Chat-widget rendering configuration (theme, copy, consent prompt). Only relevant when the agent is exposed via the embeddable widget; ignored by voice-only agents.
      - `position` 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
      - `size` 'tiny' | 'compact' | 'full'
      - `mode` 'chat' | 'voice'
      - `theme` 'light' | 'dark'
      - `baseColor` string
      - `accentColor` string
      - `agentBubbleColor` string
      - `textOnAccentColor` string
      - `secondaryTextColor` string
      - `primaryTextColor` string
      - `startButtonText` string
      - `endButtonText` string
      - `ctaName` string
      - `widgetName` string
      - `avatarUrl` string, nullable
      - `chatPlaceholder` string
      - `consentRequired` boolean
      - `consentTitle` string
      - `consentContent` string — Long-form consent body shown before the user can interact.
      - `assistantId` string, nullable
      - `allowlist` string[] — Allowed origin hostnames for widget embedding.
    - `_resolvedConfig` object — The resolved config of the target version, merged into a flat shape. Not returned in list responses (`GET /agent`). Only populated in single-agent responses (`GET /agent/{id}`) when the agent has a published, activated version. Can contain up to ~30 fields depending on which config sections are set.
      - `prompt` string — Active version's single-prompt text.
      - `tools` Tool[] — Active version's configured tools.
        - `type` 'end_call' | 'transfer_call' | 'api_call' | 'extract_dynamic_variables' | 'knowledge_base_search', required — The type of function/tool
        - `name` string, required — Unique name for the function (no spaces)
        - `description` string, required — Description of what the function does
        - `enabled` boolean — Whether the tool is enabled
        - `transferNumber` string — Required for transfer_call type. Phone number to transfer the call to (E.164 format)
        - `transferOption` object — Required for transfer_call type. Controls cold vs warm transfer behavior.
          - `type` 'cold_transfer' | 'warm_transfer' — Transfer mode. `cold_transfer` hands off immediately; `warm_transfer` briefs the receiving party first.
          - `privateHandoffOption` object, nullable — Private briefing delivered to the transfer target before the caller is connected. Only used when `type = warm_transfer`.
            - `type` 'prompt' | 'static' — `prompt` generates briefing from the LLM; `static` plays fixed text.
            - `prompt` string — The prompt or static text for the private handoff.
          - `publicHandoffOption` object, nullable — Message played to the caller while the transfer is being set up. Only used when `type = warm_transfer`.
            - `type` 'prompt' | 'static'
            - `prompt` string
        - `onHoldMusic` 'ringtone' | 'relaxing_sound' | 'uplifting_beats' | 'none' — Optional for transfer_call type. Audio played to the caller while the transfer is in progress.
        - `transferOnlyIfHuman` boolean — Optional for transfer_call type. If true, the call is only transferred when a human is detected on the receiving end (voicemail/IVR skipped).
        - `detectionTimeout` integer — Optional for transfer_call type. Seconds to wait for human detection before giving up (5–60).
        - `url` string, uri — Required for api_call type. The URL to make the HTTP request to.
        - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' — Required for api_call type. HTTP method to use.
        - `timeout` integer — Optional for api_call type. Request timeout in milliseconds (1000–30000).
        - `headers` object — Optional for api_call type. Static HTTP headers as a key/value map.
        - `headersArray` object[] — Optional for api_call type. Headers as an array of key/value objects (alternative to `headers` map).
          - `key` string, required
          - `value` string, required
        - `queryParams` object[] — Optional for api_call type. Query parameters to include in the request URL. Values support variable templating like `{{order_id}}`.
          - `key` string, required
          - `value` string, required
        - `requestBody` string — Optional for api_call type. Raw request body as a JSON string. Supports variable templating.
        - `llmParameters` object[] — Optional for api_call type. Parameters the LLM can supply dynamically at runtime.
          - `name` string, required — Parameter name
          - `description` string, required — What the parameter represents
          - `type` 'text' | 'number' | 'boolean' | 'enum', required
          - `values` string[] — Required when type is `enum`. Allowed values.
          - `required` boolean
        - `responseVariables` object[] — Optional for api_call type. Variables to extract from the API response into the agent's variable store.
          - `variableName` string, required — Name to store the extracted value under
          - `jsonPath` string, required — JSON path to extract the value from the response
        - `variablesExtractionSchema` object[] — Required for extract_dynamic_variables type. Schema defining variables to extract from the conversation.
          - `name` string, required — Name of the variable to extract
          - `description` string, required — What this variable represents
          - `type` 'text' | 'number' | 'boolean' | 'enum', required
          - `values` string[] — Required when type is `enum`. List of possible values.
        - `knowledgeBaseId` string — Required for knowledge_base_search type. ID of the knowledge base to search.
        - `fillerPhrases` string[] — Optional for knowledge_base_search type. Phrases spoken while searching.
      - `postCallAnalyticsConfig` PostCallAnalyticsConfig — Per-agent post-call analytics configuration. Evaluated after each call ends and surfaced in call logs under the `postCallAnalytics` field.
        - `dispositionMetrics` DispositionMetric[] — Structured metrics extracted from each completed call.
          - `identifier` string, required — Stable machine identifier. Lowercase letters, digits, and underscores only.
          - `dispositionMetricPrompt` string, required — Natural-language question evaluated against the transcript after the call ends.
          - `dispositionMetricType` 'STRING' | 'BOOLEAN' | 'INTEGER' | 'ENUM' | 'DATETIME', required — Data type returned by the metric.
          - `choices` string[] — Required when `dispositionMetricType = ENUM`. Allowed values.
        - `successMetrics` object[] — **Deprecated** — will be removed in a future version. Use `dispositionMetrics` instead. Kept here because the backend still accepts it on writes and returns it on reads.
          - `identifier` string, required
          - `successMetricPrompt` string, required
          - `successMetricType` 'NUMERIC_SCALE' | 'PERCENTAGE_SCALE' | 'PASS_FAIL' | 'DESCRIPTIVE_SCALE', required
        - `summaryPrompt` string — **Deprecated** — no longer used in post-call analysis and will be removed in a future version. Kept here because the backend still accepts it on writes and returns it on reads.
        - `useInternalAnalyticsModel` boolean — Use the internal analytics model. When false, falls back to the agent's own LLM.
        - `useReasoningModel` boolean — Route analytics evaluation through the reasoning model for higher-quality results at a latency/cost tradeoff.
      - `callDispositionConfig` string
      - `modelName` string — LLM model name on the resolved version.
      - `transcriberType` string — STT engine in use on the resolved version.
      - `defaultLanguage` 'en' | 'hi' | 'mr' | 'gu' | 'ta' | 'es' | 'north_indic' | 'bn' | 'or' — Default language set on the resolved version.
      - `supportedLanguages` string[] — Supported languages on the resolved version.
      - `languageSwitching` object — Language-switching configuration on the resolved version.
      - `firstMessage` string — Opening message on the resolved version.
      - `globalPrompt` string — Global prompt on the resolved version (workflow_graph agents only).
      - `preCallAPI` object — Pre-call API configuration on the resolved version.
      - `workflowGraph` object — Full node graph for workflow_graph agents. Null for single_prompt agents.
      - `muteUserUntilFirstBotResponse` boolean
      - `allowInterruptions` boolean
      - `voiceDetectionConfig` object
      - `smartTurnConfig` object
      - `backgroundSound` string
      - `denoisingConfig` object
      - `redactionConfig` object
      - `llmIdleTimeoutConfig` object
      - `sessionTimeoutConfig` object
    - `_configSource` 'active' | 'draft' | 'version' — Only present when `?draftId` or `?versionId` query params are used. Indicates which config source was resolved into `_resolvedConfig`.
    - `_versionedWorkflow` object — **Deprecated — internal use only.** Legacy field present whenever `_resolvedConfig` is populated. Mirrors a subset of `_resolvedConfig` (`prompt`, `tools`, `workflowGraph`). Kept for backward compatibility with existing frontend code. Ignore in new integrations.
      - `prompt` string
      - `tools` Tool[]
        - `type` 'end_call' | 'transfer_call' | 'api_call' | 'extract_dynamic_variables' | 'knowledge_base_search', required — The type of function/tool
        - `name` string, required — Unique name for the function (no spaces)
        - `description` string, required — Description of what the function does
        - `enabled` boolean — Whether the tool is enabled
        - `transferNumber` string — Required for transfer_call type. Phone number to transfer the call to (E.164 format)
        - `transferOption` object — Required for transfer_call type. Controls cold vs warm transfer behavior.
          - `type` 'cold_transfer' | 'warm_transfer' — Transfer mode. `cold_transfer` hands off immediately; `warm_transfer` briefs the receiving party first.
          - `privateHandoffOption` object, nullable — Private briefing delivered to the transfer target before the caller is connected. Only used when `type = warm_transfer`.
            - `type` 'prompt' | 'static' — `prompt` generates briefing from the LLM; `static` plays fixed text.
            - `prompt` string — The prompt or static text for the private handoff.
          - `publicHandoffOption` object, nullable — Message played to the caller while the transfer is being set up. Only used when `type = warm_transfer`.
            - `type` 'prompt' | 'static'
            - `prompt` string
        - `onHoldMusic` 'ringtone' | 'relaxing_sound' | 'uplifting_beats' | 'none' — Optional for transfer_call type. Audio played to the caller while the transfer is in progress.
        - `transferOnlyIfHuman` boolean — Optional for transfer_call type. If true, the call is only transferred when a human is detected on the receiving end (voicemail/IVR skipped).
        - `detectionTimeout` integer — Optional for transfer_call type. Seconds to wait for human detection before giving up (5–60).
        - `url` string, uri — Required for api_call type. The URL to make the HTTP request to.
        - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' — Required for api_call type. HTTP method to use.
        - `timeout` integer — Optional for api_call type. Request timeout in milliseconds (1000–30000).
        - `headers` object — Optional for api_call type. Static HTTP headers as a key/value map.
        - `headersArray` object[] — Optional for api_call type. Headers as an array of key/value objects (alternative to `headers` map).
          - `key` string, required
          - `value` string, required
        - `queryParams` object[] — Optional for api_call type. Query parameters to include in the request URL. Values support variable templating like `{{order_id}}`.
          - `key` string, required
          - `value` string, required
        - `requestBody` string — Optional for api_call type. Raw request body as a JSON string. Supports variable templating.
        - `llmParameters` object[] — Optional for api_call type. Parameters the LLM can supply dynamically at runtime.
          - `name` string, required — Parameter name
          - `description` string, required — What the parameter represents
          - `type` 'text' | 'number' | 'boolean' | 'enum', required
          - `values` string[] — Required when type is `enum`. Allowed values.
          - `required` boolean
        - `responseVariables` object[] — Optional for api_call type. Variables to extract from the API response into the agent's variable store.
          - `variableName` string, required — Name to store the extracted value under
          - `jsonPath` string, required — JSON path to extract the value from the response
        - `variablesExtractionSchema` object[] — Required for extract_dynamic_variables type. Schema defining variables to extract from the conversation.
          - `name` string, required — Name of the variable to extract
          - `description` string, required — What this variable represents
          - `type` 'text' | 'number' | 'boolean' | 'enum', required
          - `values` string[] — Required when type is `enum`. List of possible values.
        - `knowledgeBaseId` string — Required for knowledge_base_search type. ID of the knowledge base to search.
        - `fillerPhrases` string[] — Optional for knowledge_base_search type. Phrases spoken while searching.
      - `workflowGraph` object

## Other responses

- `400` — Invalid input
- `401` — Unauthorized access
- `403` — Forbidden access
- `500` — Internal server error

---

[API](https://skmtc.net/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.net/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/versions/6d1036a76fbc/schema)