---
name: "phone_list_calls"
area: "phone"
title: "List phone calls"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/phone_list_calls"
mcp_server: "https://api.conecto.chat/mcp/phone"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/phone/phone_list_calls"
---

# List phone calls (`phone_list_calls`)

Calls to and from the business's numbers, newest first: who, when, how long and what it cost, missed ones included.

Calls to and from the business's numbers, newest first: who, when, how long and what it cost. Missed calls (outside hours, paused, balance too low, lines busy) are included with the reason, and so are the calls the assistant made to confirm meetings. When the balance was too low the caller could leave a message, free: it is on the missed call as left_message. Read a whole conversation with phone_get_call.

Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing.

## Use it when

Someone asks who called, or whether calls were missed.

- For one call with its whole transcript, use [phone_get_call](https://conecto.chat/tools/phone/phone_get_call.md).

## Say this to your agent

> Who called yesterday, and did we miss anyone?

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `limit` | integer | no | 1 to 100. |  | `20` |
| `before` | string (date-time) | no | Only calls before this time (ISO 8601), to page back. |  |  |
| `include_missed` | boolean | no |  |  | `true` |

## Example

Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon.

MCP: call `phone_list_calls` on the MCP server `https://api.conecto.chat/mcp/phone` with these arguments:

```json
{
  "limit": 20
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/phone_list_calls \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 20}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "phone_list_calls",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "calls": [
      {
        "call_id": "a3f5c2d1-9b8e-4f70-8c6d-2e1b0a9f8c7d",
        "direction": "inbound",
        "from": "+15035550187",
        "to": "+15035550123",
        "at": "2026-10-13T16:42:10+00:00",
        "status": "ended",
        "answered": true,
        "duration_seconds": 146,
        "cost_usd": "$0.75",
        "summary": "Asked whether the Tabor comes in a 52 cm frame and how long a build takes."
      },
      {
        "call_id": null,
        "from": "+15035550142",
        "to": "+15035550123",
        "at": "2026-10-13T03:12:44+00:00",
        "status": "missed",
        "reason": "outside_hours",
        "message": "The call came outside the answering hours.",
        "cost_usd": "$0.00"
      }
    ],
    "count": 2
  }
}
```

`result`: Calls newest first, each with its call_id, direction, from, to, time, status, whether it was answered, duration, cost and summary; missed calls with their reason, and left_message (its words, length and recording) when the balance was too low and the caller left a message; and how many.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `invalid_input` | 400 | before is not an ISO 8601 time. | Send it like 2026-10-12T09:00:00Z. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [phone_search_numbers](https://conecto.chat/tools/phone/phone_search_numbers.md): Phone numbers the business can rent right now, each with the monthly price and a quote to rent it. Free up to 1,000,000 reads a month.
- [phone_rent_number](https://conecto.chat/tools/phone/phone_rent_number.md): Rents a number found by phone_search_numbers; this call pays the first month. Quoted, up to $25.00.
- [phone_setup_assistant](https://conecto.chat/tools/phone/phone_setup_assistant.md): Sets how the business's numbers answer (the agent's webhook or taking messages), the greeting, voice and hours, and whether messages become tickets. $0.001 a call.
- [phone_get_assistant](https://conecto.chat/tools/phone/phone_get_assistant.md): How the business's numbers answer, whether they answer right now (and why not), and the voices to choose from. Free up to 1,000,000 reads a month.
- [phone_list_numbers](https://conecto.chat/tools/phone/phone_list_numbers.md): The numbers the business rents, with their monthly price and next renewal. Free up to 1,000,000 reads a month.
- [phone_get_call](https://conecto.chat/tools/phone/phone_get_call.md): One call with its whole transcript: who said what, and when. Free up to 1,000,000 reads a month.
- [phone_release_number](https://conecto.chat/tools/phone/phone_release_number.md): Gives a number back for good: it stops answering at once and its rent ends. Free.