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
Section titled “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
Section titled “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
Section titled “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
Section titled “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. |