# Fetch a single agent

Source: https://docs.usetone.ai/reference/agents/findById

> Returns the WORKING COPY — what an edit would change and what the next publish would freeze.

`GET /v1/agents/{id}`
Returns the WORKING COPY — what an edit would change and what the next publish would freeze. To read what actually ran on a call, fetch that version by number instead.

Requires the `read` scope.

## Parameters

| Name | In | | Meaning |
|---|---|---|---|
| `id` | path | required | The agent's id. |

## Response

| Field | Type | | Meaning |
|---|---|---|---|
| `callSettings` | object | required | How a call RUNS — ambience, quiet-caller nudges, voicemail handling, length cap, farewell. |
| `createdAt` | string | required | When the agent was created. RFC 3339, UTC. |
| `evaluationCriteria` | object | required | What the post-call judge grades each call against; produces `calls.evaluations`. |
| `id` | string | required | The agent's unique id. |
| `inputVariables` | object | required | Declared `{{placeholders}}` the prompt can use, with their defaults. Values are supplied per call via `variables`. |
| `knowledgeBaseIds` | string[] | required | Knowledge bases this agent may answer from. |
| `languages` | string[] | required | What the agent SPEAKS, primary first. A detected language outside this list is clamped to it. |
| `llmProvider` | string | required | Who supplies the language model. Open set — read the current options from GET /v1/catalog/voice. |
| `name` | string | required | Your name for the agent. |
| `outputVariables` | object | required | The post-call extraction schema — what shapes `calls.outputs`. |
| `purpose` | string | required | The regulatory classification of calls this agent places. Drives the calling-window rules the compliance gate enforces — it is not cosmetic, and there is deliberately no per-call override. Open set — handle an unrecognised value rather than throwing. Today: `promotional`, `service`, `transactional`, `collections`. |
| `status` | string | required | A `draft` agent can still be dialled outbound; an INBOUND call is refused until it is `live`, because a half-written prompt should not answer a real customer. Open set — handle an unrecognised value rather than throwing. Today: `draft`, `live`. |
| `sttLanguage` | string | null | required | Pinned recognition language, or null to auto-detect. |
| `sttMode` | string | required | How the transcriber is asked to handle language — transcribing faithfully versus translating. Open set. |
| `sttModel` | string | required | Speech-to-text model id. |
| `sttProvider` | string | required | Who supplies speech-to-text. Open set. |
| `systemPrompt` | string | required | The agent’s instructions, verbatim. |
| `tools` | object | required | Custom API tools the agent may call mid-conversation. Credentials appear only as `secretId` references, never inline. |
| `ttsModel` | string | required | Text-to-speech model id, e.g. `bulbul:v3`. |
| `ttsOptions` | object | required | Voice tuning (pace, and model-specific fields). The legal keys and ranges differ per TTS model and are documented on the agent write schemas. |
| `ttsProvider` | string | required | Who supplies text-to-speech. Open set. |
| `ttsVoice` | string | required | Speaker id. NOT portable across model versions — a voice valid on `bulbul:v3` is a 400 on `bulbul:v2`. `GET /v1/catalog/voice` lists the legal pairings. |
| `updatedAt` | string | required | When the agent was last changed. RFC 3339, UTC. |

### Example response

```json
{
  "data": {
    "callSettings": {
      "background": {
        "sound": "none",
        "volume": 0.3
      },
      "hangupLine": {
        "text": "Thanks for your time. Goodbye."
      },
      "maxCallSeconds": 600,
      "nudges": {
        "enabled": true,
        "hangupAfter": true,
        "steps": [
          {
            "afterSeconds": 15,
            "line": {
              "text": null
            }
          }
        ]
      },
      "openingLine": {
        "text": "Hi {{customer_name}}, I’m calling from Acme about your order."
      },
      "voicemail": {
        "enabled": true,
        "windowSeconds": 30
      }
    },
    "createdAt": "2026-08-25T09:14:22Z",
    "evaluationCriteria": [
      {
        "id": "confirmed_order",
        "name": "Confirmed the order",
        "prompt": "Did the customer explicitly confirm they still want the order?"
      }
    ],
    "id": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",
    "inputVariables": [
      {
        "default": "there",
        "description": "The customer’s first name, as it appears on the order.",
        "name": "customer_name"
      }
    ],
    "knowledgeBaseIds": [
      "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451"
    ],
    "languages": [
      "hi-IN",
      "en-IN"
    ],
    "llmProvider": "google",
    "name": "Order confirmation",
    "outputVariables": [
      {
        "description": "Which day the customer agreed to take delivery. Leave empty if they did not commit to one.",
        "enumValues": [
          "monday",
          "tuesday",
          "wednesday"
        ],
        "name": "delivery_day",
        "type": "enum"
      }
    ],
    "purpose": "promotional",
    "status": "draft",
    "sttLanguage": "auto",
    "sttMode": "transcribe",
    "sttModel": "saaras:v3",
    "sttProvider": "sarvam",
    "systemPrompt": "You call customers to confirm a cash-on-delivery order…",
    "tools": [
      {
        "connectionId": "b4e6d8a1-9c3f-4b2e-8d7a-1f0e9c8b7a6d",
        "description": "Call this once the customer has agreed to a specific delivery date and time window.",
        "http": {
          "auth": {
            "header": "x-api-key",
            "in": "header",
            "name": "api_key",
            "secondary": {
              "in": "header",
              "name": "x-acme-secret",
              "secretId": "7c2b8e5d-1a3f-4e6b-8c9d-0e1f2a3b4c5d"
            },
            "secretId": "3f1a7f6e-2b4c-4d1e-9a8b-5c6d7e8f9a0b",
            "type": "bearer"
          },
          "bodyFormat": "json",
          "bodyRoot": "object",
          "headers": {
            "x-acme-source": "tone"
          },
          "method": "POST",
          "timeoutMs": 5000,
          "url": "https://api.acme.example/v1/deliveries"
        },
        "mock": {
          "enabled": true,
          "response": "{\"status\":\"booked\",\"slot\":\"2026-09-02T10:00:00+05:30\"}"
        },
        "name": "book_delivery_slot",
        "parameters": [
          {
            "description": "The agreed date as YYYY-MM-DD.",
            "name": "delivery_date",
            "required": true,
            "type": "string"
          }
        ],
        "preset": "cal.com/book",
        "speech": {
          "en-IN": "Let me check that for you.",
          "hi-IN": "मैं अभी देखता हूँ।"
        }
      }
    ],
    "ttsModel": "bulbul:v3",
    "ttsOptions": {
      "pace": 1
    },
    "ttsProvider": "sarvam",
    "ttsVoice": "simran",
    "updatedAt": "2026-08-25T09:14:22Z"
  }
}
```