# Place and read calls (/guides/direct-calls)

This guide covers the two halves of the Calls API: **placing** a single call with [`POST /api/v1/calls/`](/api-reference/calls/createCall), and **reading** calls, transcripts, recordings and reports afterwards.

## Pick the right way to call [#pick-the-right-way-to-call]

| You want to | Use |
| --- | --- |
| Call one number now with an agent, no campaign set up | [`POST /api/v1/calls/`](/api-reference/calls/createCall) (this page) |
| Call many leads on a schedule, with a calling window, retries and a daily limit | A campaign ([Campaigns](/guides/campaigns)) |
| Call a lead that is already on a running campaign, right now | [`POST /api/v1/instant/call-now`](/api-reference/calls/callNow) with `leadId` and `campaignId` |
| Call a lead through the first running campaign it belongs to | [`POST /api/v1/leads/{lead_id}/call-now`](/api-reference/calls/callLeadNow) |
| Try an agent before going live | [`POST /api/v1/agents/{agent_id}/test-call`](/api-reference/agents/testCallAgent) |

The two call-now endpoints use the campaign's agent and phone numbers and answer `200` with the same body as `POST /calls`. They do not accept `Idempotency-Key`.

## Place a call [#place-a-call]

`POST /api/v1/calls/` calls `to` now with the agent. You need a key with **full** access that can reach **Calls** ([Authentication](/authentication)).

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl -X POST https://api.callmitra.ai/api/v1/calls/ \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -H "Idempotency-Key: order-A-1042-delivery-call" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23",
    "to": "+919812345678",
    "name": "Asha Verma",
    "variables": { "order_id": "A-1042", "delivery_date": "Friday" },
    "metadata": { "crmId": "0065g00000XyZ" }
  }'
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch('https://api.callmitra.ai/api/v1/calls/', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CALLMITRA_API_KEY,
    'Idempotency-Key': 'order-A-1042-delivery-call',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agentId: '4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23',
    to: '+919812345678',
    name: 'Asha Verma',
    variables: { order_id: 'A-1042', delivery_date: 'Friday' },
    metadata: { crmId: '0065g00000XyZ' },
  }),
});
const body = await res.json();
if (res.status !== 201) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.call.id);
```
</Tab>

<Tab value="Python">
```python
import os
import requests

res = requests.post(
    "https://api.callmitra.ai/api/v1/calls/",
    headers={
        "X-API-Key": os.environ["CALLMITRA_API_KEY"],
        "Idempotency-Key": "order-A-1042-delivery-call",
    },
    json={
        "agentId": "4f6d2c1a-9b7e-4c3d-8a21-5e0f7b9c1d23",
        "to": "+919812345678",
        "name": "Asha Verma",
        "variables": {"order_id": "A-1042", "delivery_date": "Friday"},
        "metadata": {"crmId": "0065g00000XyZ"},
    },
    timeout=30,
)
body = res.json()
if res.status_code != 201:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["call"]["id"])
```
</Tab>
</Tabs>

### Request body [#request-body]

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agentId` | string | yes | Agent that speaks on the call ([`GET /agents`](/api-reference/agents/listAgents)). An archived agent answers `422` [`agent_state_blocked`](/errors/agent_state_blocked). |
| `to` | string | yes | Number to call, E.164, up to 32 characters. Spaces, dashes, dots and brackets are removed first; the rest must be `+` and 7 to 15 digits, not starting with `0`. Otherwise `422` [`invalid_phone_number`](/errors/invalid_phone_number). |
| `fromNumberId` | string | no | ID of your phone number to call from ([`GET /phone-numbers`](/api-reference/phone-numbers/listPhoneNumbers)). Omitted: a free number from the agent's phone numbers. |
| `leadId` | string | no | Lead this call belongs to. Its phone must match `to`. |
| `name` | string | no | Name for a new lead, up to 255 characters. Ignored when the lead already exists. |
| `variables` | object | no | Up to 50 values the agent's script can use as `{{name}}`. Values are strings, numbers or booleans. Keys use letters, digits and underscores, do not start with a digit, and are at most 64 characters. |
| `metadata` | object | no | Your own data, at most 4096 bytes of JSON. Never spoken. Returned unchanged as `metadata` on the call. |

Any other field is rejected with `422` [`parameter_invalid`](/errors/parameter_invalid). There is no per-call webhook URL: results go to your workspace's [webhooks](/webhooks).

### Which lead the call belongs to [#which-lead-the-call-belongs-to]

Every call belongs to a lead, so the call shows up in your reports and lead history:

1. With `leadId`, that lead is used. A lead from another workspace answers `404` [`lead_not_found`](/errors/lead_not_found); a lead whose phone does not match `to` answers `422` [`parameter_invalid`](/errors/parameter_invalid) with `param: "leadId"`.
2. Without `leadId`, CallMitra uses the newest lead in your workspace with exactly this number.
3. If there is none, it creates a lead with `source: "api"`, named `name` (or the number itself when you send no `name`).

### Caller ID [#caller-id]

The call runs on the agent's **instant campaign**: a campaign CallMitra creates for the agent the first time it is needed, named after the agent with ` Instant` at the end. Its numbers are the agent's numbers.

- Without `fromNumberId`, CallMitra picks a free number from that pool.
- With `fromNumberId`, only that number is used. A number not in your workspace answers `404` [`phone_number_not_found`](/errors/phone_number_not_found). A number that is inactive or has no outbound carrier credentials answers `422` [`phone_number_not_dialable`](/errors/phone_number_not_dialable).

### Response [#response]

`201 Created` means the carrier accepted the dial. It does not mean the call was answered. Follow the call with [`GET /calls/{call_id}`](/api-reference/calls/getCall) or the [`call.completed`](/webhooks/events) webhook.

```json title="201 Created"
{
  "success": true,
  "call": {
    "id": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65",
    "leadId": "b2a7c9d1-6e3f-4a8b-9c0d-1e2f3a4b5c6d",
    "leadName": "Asha Verma",
    "campaignId": "e3f4a5b6-c7d8-4e9f-a0b1-c2d3e4f5a6b7",
    "campaignName": "Delivery desk Instant",
    "providerCallId": "CA5f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c",
    "status": "queued",
    "phoneNumber": "+919812345678",
    "phoneNumberId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  }
}
```

| Field | Meaning |
| --- | --- |
| `call.id` | Call ID. Use it with every read endpoint below. |
| `call.leadId`, `call.leadName` | The lead that was used or created. |
| `call.campaignId`, `call.campaignName` | The agent's instant campaign. |
| `call.providerCallId` | The carrier's call ID. |
| `call.status` | Carrier status at dial time, usually `initiated` or `queued`. |
| `call.phoneNumber` | The number being dialed. |
| `call.phoneNumberId` | Your phone number the call is placed from. |
| `sipResponse` | The carrier's raw answer to the dial request, when present. Fields vary by carrier; do not depend on them. |

### One request, one dial [#one-request-one-dial]

Each `POST /calls` dials once.

- A call that is not answered, is busy or times out is **not** redialed.
- A refused dial is **not** queued to try later. The lead does not stay queued on the agent's instant campaign.
- For a second attempt, place another call. Use a new `Idempotency-Key`, or the first result is replayed.
- One exception: the callee may ask to be called back, and the agent may book that callback during the call. The booked callback is placed at the agreed time.

## Retry safely with Idempotency-Key [#retry-safely-with-idempotency-key]

A timeout does not tell you whether the call was placed. Send an `Idempotency-Key` header (1 to 255 characters) and reuse it when you retry the same request. Within 24 hours, the same key with the same body returns the first result with `Idempotent-Replayed: true` instead of calling again. The full rules are in [Idempotency](/idempotency).

<Callout type="warn" title="Refusals are replayed too">
Client errors (`4xx`) are stored like successes, except `401`, `403`, `404` and `429`. If a call was refused with `409` [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached) and you retry later with the **same** key, you get the same `409` back. Once the refusal is resolved, try again with a **new** key. `5xx`, `401`, `403`, `404` and `429` responses are not stored, so a retry with the same key runs again.
</Callout>

## Limits and refusals [#limits-and-refusals]

These limits apply to every direct call. Each refusal has its own code, and the error body follows the usual [error format](/errors).

| What | Status and code | What to do |
| --- | --- | --- |
| `to` is outside your workspace's home country. The home country comes from your billing address (India when none is set); support can enable more countries. | `422` [`destination_not_allowed`](/errors/destination_not_allowed), `param: "to"` | The message lists the allowed codes, for example `+91`. Contact support to call other countries. |
| Your workspace placed its daily number of calls through `POST /calls`. The count runs per UTC day. | `429` [`daily_call_limit_reached`](/errors/daily_call_limit_reached) | Wait for `Retry-After` (seconds until 00:00 UTC). Use a [campaign](/guides/campaigns) for large volumes, or ask support to raise the limit. |
| The daily call counter is briefly unavailable. Direct calls fail closed. | `503` [`service_unavailable`](/errors/service_unavailable) | Retry shortly. |
| The number is on your do-not-call list. Any lead in your workspace with this number (same number, or same last 10 digits) that opted out blocks the call. | `409` [`number_on_dnc`](/errors/number_on_dnc) | Do not call. Remove the number from do-not-call only if the person agreed to be called again. |
| The agent's instant campaign already has a call in progress. By default it runs one call at a time, so one agent places one direct call at a time. | `409` [`campaign_call_limit_reached`](/errors/campaign_call_limit_reached) | `detail.activeCallId` is the call in progress. Retry when it ends. |
| Another call for the same agent is being placed at this moment. | `409` [`campaign_dial_busy`](/errors/campaign_dial_busy) | Wait a second and retry. |
| This lead already has a call ringing or connected. | `409` [`lead_call_in_progress`](/errors/lead_call_in_progress) | Retry after it ends. |
| Your plan's limit on simultaneous calls is in use. | `429` [`concurrent_call_limit_reached`](/errors/concurrent_call_limit_reached) | Retry when a call ends. |
| The workspace is out of balance or has no plan that covers calls. | `402` [`payment_required`](/errors/payment_required) | Top up or change the plan. |
| The calling number or its carrier account is at its call limit. | `409` [`carrier_capacity_reached`](/errors/carrier_capacity_reached) | Retry in a moment. |
| The agent's instant campaign is stopped. | `409` [`campaign_not_running`](/errors/campaign_not_running) | Start it with [`POST /campaigns/{campaign_id}/start`](/api-reference/campaigns/startCampaign). |
| The carrier refused the dial before it rang. | `400` [`dial_rejected`](/errors/dial_rejected) | Read the message. The failed call is recorded; its ID is in `detail.call.id`. |
| The carrier could not be reached. | `502` [`dial_failed`](/errors/dial_failed) | Retry. The failed call is recorded in `detail.call.id`. |
| The agent has no usable phone number, or another request problem. | `400` [`bad_request`](/errors/bad_request) | Read the message and fix the setup. |

The [API reference](/api-reference/calls/createCall) lists every code this endpoint can return. Your key's [rate limit](/rate-limits) also applies.

<Callout type="warn" title="No calling-window check on direct calls">
A direct call is placed the moment you ask, at any hour. CallMitra does **not** check a calling window or time-of-day rules for `POST /calls`, `POST /instant/call-now` or `POST /leads/{lead_id}/call-now`. The do-not-call list is still checked. You are responsible for consent and for calling only at hours the rules allow, including TRAI rules for Indian numbers. See [Calling in India](/guides/india-calling).
</Callout>

## Read calls [#read-calls]

All read endpoints work with a read-only key that can reach **Calls**.

### List calls [#list-calls]

[`GET /api/v1/calls/`](/api-reference/calls/listCalls) returns calls newest first.

| Parameter | Default | Notes |
| --- | --- | --- |
| `cursor` | | Send it empty for the first page, then the `nextCursor` from the previous response. Cursor pages skip the total count and stay fast on long lists. |
| `page` | `1` | Page number, from 1. Ignored when `cursor` is sent. |
| `limit` | `25` | Items per page, 1 to 200. |
| `search` | | Matches the phone number, customer name or phone, summary, or call name. |
| `agentId`, `leadId`, `campaignId` | | Only calls of this agent, lead or campaign. |
| `outcome` | | `qualified`, `interested`, `callback`, `not_interested`, `no_response`, `no_answer`, `busy`, `call_failed` or `voicemail`. |
| `sentiment` | | `positive`, `neutral` or `negative`. |
| `channel` | | `inbound`, `browser` (test calls), or `instant` / `bulk` (calls by agents in that calling mode). |
| `hasRecording` | | `true` or `false`. |
| `dateFilter` | `all` | `today` (since 00:00 UTC), `week` (last 7 days), `month` (last 30 days) or `all`. |
| `includeTests` | `true` | Set `false` to leave out test calls. |

There are two ways to page:

- **Cursor mode** (recommended for syncing): pass `cursor=` on the first request. Each response has top-level `nextCursor` and `hasMore`. `nextCursor` is `null` on the last page. The `pagination` object only has `itemsPerPage`, `hasNextPage` and `nextCursor`.
- **Page mode**: omit `cursor`. `pagination` has `currentPage`, `totalPages`, `totalItems`, `itemsPerPage`, `hasNextPage` and `hasPreviousPage`. Matches are counted up to 10,000; above that `totalCapped` is `true` and `totalItems` is only a lower bound.

An unreadable cursor answers `422` [`parameter_invalid`](/errors/parameter_invalid). See [Pagination](/pagination).

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl -G https://api.callmitra.ai/api/v1/calls/ \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  --data-urlencode "cursor=" \
  --data-urlencode "limit=100" \
  --data-urlencode "includeTests=false"
```
</Tab>

<Tab value="Node.js">
```js
let cursor = '';
do {
  const url = new URL('https://api.callmitra.ai/api/v1/calls/');
  url.search = new URLSearchParams({ cursor, limit: '100', includeTests: 'false' });
  const res = await fetch(url, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } });
  const page = await res.json();
  for (const call of page.calls) console.log(call.id, call.status);
  cursor = page.nextCursor;
} while (cursor);
```
</Tab>

<Tab value="Python">
```python
cursor = ""
while cursor is not None:
    page = requests.get(
        "https://api.callmitra.ai/api/v1/calls/",
        headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
        params={"cursor": cursor, "limit": 100, "includeTests": "false"},
        timeout=30,
    ).json()
    for call in page["calls"]:
        print(call["id"], call["status"])
    cursor = page["nextCursor"]
```
</Tab>
</Tabs>

### Get one call [#get-one-call]

[`GET /api/v1/calls/{call_id}`](/api-reference/calls/getCall) returns `{ "success": true, "call": { ... } }`. An unknown ID, or a call in another workspace, answers `404` [`call_not_found`](/errors/call_not_found). The fields you will use most:

| Field | Meaning |
| --- | --- |
| `status` | `initiated`, `ringing`, `answered`, `completed`, `no_answer`, `busy` or `failed`. |
| `callType` | `manual` for direct and call-now calls; also `campaign`, `inbound` or `browser`. |
| `startTime`, `endTime`, `duration` | ISO 8601 times and talk time in seconds. |
| `outcome`, `outcomeCategory`, `merchantOutcome` | `successful` or `failed`; the detailed disposition; the outcome shown in the console. |
| `endedReason`, `failureReason` | Why the call ended, and why it failed when it did. |
| `summary`, `sentiment`, `callAnalysis` | AI summary, sentiment, and post-call analysis when the agent has it on. |
| `extractedFields` | Details the agent collected, keyed by your capture fields. |
| `transcript` | `User:` / `Assistant:` lines. Use the transcript endpoint for parsed turns. |
| `hasRecording` | Whether a recording can be downloaded. |
| `billableMinutes`, `billedInr` | Minutes charged, and the amount in rupees. |
| `metadata` | The `metadata` you sent with `POST /calls`, unchanged. |
| `fromNumber`, `phoneNumber`, `phoneNumberId` | Caller ID used, the other party's number, and your number's ID. |

### Transcript [#transcript]

[`GET /api/v1/calls/{call_id}/transcript`](/api-reference/calls/getCallTranscript) returns the conversation as text and as ordered turns, plus the tools the agent called. `role` is `user` (the other party) or `assistant` (your agent). The transcript is empty while nothing has been said, and final once the call has ended.

```json
{
  "success": true,
  "callId": "8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65",
  "status": "completed",
  "transcript": "Assistant: Hi, this is Asha from Acme.\nUser: Hi, yes.",
  "turns": [
    { "role": "assistant", "text": "Hi, this is Asha from Acme." },
    { "role": "user", "text": "Hi, yes." }
  ],
  "toolInvocations": []
}
```

### Recording [#recording]

[`GET /api/v1/calls/{call_id}/recording`](/api-reference/calls/getCallRecording) returns the audio file itself, authenticated with your key like any other request. Check `hasRecording` on the call first.

- Format: stereo MP3 (`audio/mpeg`). An older call that has not been converted yet is served as WAV (`audio/wav`). Read the `Content-Type` header.
- `404` [`call_recording_not_found`](/errors/call_recording_not_found): the call was not answered, recording was off, or the audio is still being saved. Retry a minute after the call ends.
- `410` [`call_recording_deleted`](/errors/call_recording_deleted): your data retention policy removed the recording. It cannot be restored.

```bash
curl https://api.callmitra.ai/api/v1/calls/8c1e5b7a-2d4f-4e9a-b6c3-1f0a9d8e7b65/recording \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -o call.mp3
```

## Reports [#reports]

Both report endpoints use **India Standard Time** (`Asia/Kolkata`) to decide where a day or an hour starts.

### Calls per day [#calls-per-day]

[`GET /api/v1/calls/daily-counts`](/api-reference/calls/getCallDailyCounts) takes `days` (1 to 90, default 30), ending today. Values outside that range are clamped to it. You get one entry per day, oldest first, with zeros for days without calls, plus totals. `avgDurationSeconds` is the average length of completed calls.

```json
{
  "success": true,
  "days": 2,
  "timezone": "Asia/Kolkata",
  "totals": { "total": 12, "completed": 9, "failed": 1, "noAnswer": 2, "avgDurationSeconds": 74.2 },
  "daily": [
    { "date": "2026-11-14", "total": 5, "completed": 4, "failed": 0, "noAnswer": 1, "avgDurationSeconds": 80.0 },
    { "date": "2026-11-15", "total": 7, "completed": 5, "failed": 1, "noAnswer": 1, "avgDurationSeconds": 69.6 }
  ]
}
```

### Performance [#performance]

[`GET /api/v1/calls/performance`](/api-reference/calls/getCallPerformance) returns totals, connect rate, conversion, the outcome and channel split, calls per hour and an agent leaderboard, with the range before it for comparison.

| Parameter | Default | Notes |
| --- | --- | --- |
| `rangeDays` | `30` | `7`, `30` or `90`, ending today. Any other value means 30. |
| `agentId` | | Only calls of this agent. |
| `channel` | | `instant`, `bulk`, `inbound` or `browser`. |
| `includeTests` | `false` | Also count test calls placed from the console. |

Rates (`connectRate`, `conversion`, `successRate`) are between 0 and 1. `byHour` keys are hours `0` to `23` in IST; empty hours are left out. `recent.today` counts calls since midnight IST.

## Related [#related]

- [Campaigns](/guides/campaigns)
- [Calling in India](/guides/india-calling)
- [Webhook events](/webhooks/events)
- [Idempotency](/idempotency)
- [Workspace and usage](/guides/workspace-usage)