---
title: "Calls and reports"
url: "https://docs.teleflows.io/guides/mcp/reference/tools/calls-and-reports.md"
canonical_url: "https://docs.teleflows.io/guides/mcp/reference/tools/calls-and-reports/"
last_updated: 2026-10-01
type: reference
summary: "Reference for the 4 calls and reports tools of the Teleflows MCP server."
---

# Calls and reports

Each tool lists the inputs your assistant can send. You do not type these yourself: ask in plain language and the assistant fills them in.

## Search calls

Tool name: `teleflows_search_calls`

Lists individual calls your API key can access in a time window (at most 31 days, default the last 24 hours).

Use it to see or inspect specific calls: who called, which campaign, publisher, buyer and target, duration, status, recording and money. Do not use it to count or total calls: it returns no totals; use `teleflows_get_call_report` for counts, sums and breakdowns. Filter by campaign, buyer or publisher (IDs from the list tools) or by status; status live finds calls in progress that started within the window, so widen since for long calls. Results come in pages: pass `next_cursor` back to get the next page. Money fields are in cents and `total_cost_cents` is a string. Caller numbers may be masked and money fields missing if your key's role does not allow them. The order of calls is not documented.

**Inputs**

| Input | Details | Description |
|---|---|---|
| `since` | string; up to 40 characters | Start of the window (inclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day. Default: 24 hours before until. |
| `until` | string; up to 40 characters | End of the window (exclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day, not included. Example: yesterday on 2026-10-01 is since 2026-09-30, until 2026-10-01. Default: now. At most 31 days after since; longer windows are rejected. |
| `campaign_id` | string; 36 characters | The campaign ID (UUID). |
| `buyer_id` | string; 36 characters | The buyer ID (UUID). |
| `publisher_id` | string; 36 characters | The publisher ID (UUID). |
| `status` | string; `live`, `connected`, `ended` | Call status. |
| `limit` | integer; 1 to 50; default `25` | Calls per page, 1-50 (larger pages would exceed client result limits). |
| `cursor` | string; up to 8192 characters | `next_cursor` from a previous result. Send it alone or with the same filters. |

## Get call

Tool name: `teleflows_get_call`

Gets everything Teleflows returns about one call, by its `call_uuid` (from `teleflows_search_calls` or a report).

Use it to explain what happened on a call: status, timing, campaign, publisher, buyer, target, routing plan name, hang-up cause and money. Not for finding calls (use `teleflows_search_calls`) or totals (use `teleflows_get_call_report`). The result combines the call detail with the call's row from the call list, because each carries fields the other lacks (for example `has_recording` and `end_call_source` only exist in the list row). Money is in cents; `total_cost_cents` is a string. Caller numbers may be masked and money fields missing, depending on your key's role. Conversion details have come back empty in testing even for calls marked `has_conversion`, so an empty conversions list does not prove there was no conversion. Which workflow ran on a call is not recorded by Teleflows.

**Inputs**

| Input | Details | Description |
|---|---|---|
| `call_id` | string; required; 36 characters | The call's `call_uuid` (not `inbound_call_id`). |

## Call report

Tool name: `teleflows_get_call_report`

Totals, breakdowns and trends for calls in a time window (at most 31 days, default the last 24 hours, UTC).

Use it for any "how many / how much / which is best" question: calls, connections, conversions, revenue, payout, profit, duplicates, blocked calls, average and total call length. totals covers the whole window; groups has one row per campaign, target, publisher, buyer, tracking number, state, date or duplicate flag (`group_by`), each with every metric; totals and groups also count blocked, duplicate, live, no-connect and IVR hang-up calls; rows grouped by tracking number, state, date or duplicate have no ID to look up; timeline shows one metric (metric) over time in buckets (bucket). For a daily table with all metrics use `group_by`=date. Filters: campaign, buyer, publisher (IDs from the list tools) and call status; there is no target or tracking-number filter. Rates are calculated by Teleflows: `conversion_pct` = converted / incoming × 100; `margin_pct` = `profit_net_cents` / `revenue_cents` × 100; `rpc_cents` = `revenue_cents` / incoming; `acl_seconds` = average connected length. Money is in cents; `total_cost_cents` is a string. Money metrics need financial permissions: a 0 can mean either zero or hidden for your key's role. Windows longer than 31 days are rejected: for longer periods, request several windows; add counts and cents, but do not add or average the rates across windows. If there are more groups, pass `next_cursor`; totals and timeline come from the first page.

**Inputs**

| Input | Details | Description |
|---|---|---|
| `since` | string; up to 40 characters | Start of the window (inclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day. Default: 24 hours before until. |
| `until` | string; up to 40 characters | End of the window (exclusive): date-time with timezone, or YYYY-MM-DD meaning 00:00 UTC that day, not included. Example: yesterday on 2026-10-01 is since 2026-09-30, until 2026-10-01. Default: now. At most 31 days after since; longer windows are rejected. |
| `group_by` | string; `campaign`, `target`, `publisher`, `buyer`, `tracking_number`, `state`, `date`, `duplicate`; default `campaign` | One row per value of this dimension. |
| `metric` | string; `incoming`, `completed`, `connected`, `paid`, `converted`, `revenue`, `profit`, `tcl`, `acl`; default `incoming` | Metric for the timeline only; group rows carry every metric. |
| `bucket` | string; `minute`, `hour`, `day`, `week`, `month`; default `day` | Timeline bucket size (UTC). |
| `campaign_id` | string; 36 characters | The campaign ID (UUID). |
| `buyer_id` | string; 36 characters | The buyer ID (UUID). |
| `publisher_id` | string; 36 characters | The publisher ID (UUID). |
| `status` | string; `live`, `connected`, `ended` | Call status. |
| `limit` | integer; 1 to 100; default `50` | Groups per page, 1-100. |
| `cursor` | string; up to 8192 characters | `next_cursor` from a previous result. Send it alone or with the same filters. |

## Get call recording

Tool name: `teleflows_get_call_recording`

Checks whether a call's recording can be downloaded and, only when asked, returns a short-lived download link (valid about 10 minutes).

Set `include_link` to true only when the user explicitly asks for the link. The link is a credential: it works only together with the same Teleflows API key (a browser cannot open it on its own), and it must not be shared. To see whether a call has a recording at all, `has_recording` is in `teleflows_get_call` or `teleflows_search_calls`. Audio itself is not returned.

**Inputs**

| Input | Details | Description |
|---|---|---|
| `call_id` | string; required; 36 characters | The call's `call_uuid`. |
| `include_link` | boolean; default `false` | Return the short-lived download link. Only when the user explicitly asks for it. |
