Call Reports API
Everything the Call Center Report shows is available as JSON: headline metrics, the quality scorecard, compliance trend, contact reasons, agent performance, exemplary calls and shift comparison, plus the best practices drawn from the exemplary calls and a per-call table you can page through and drill into.
Typical uses are pulling compliance numbers into your own BI tool, mirroring per-call scores into a workforce management system, and polling for progress while a batch of uploads is being analyzed.
All endpoints accept either a session cookie or an API key — see Authentication. Results are scoped to the calling user exactly as in the web app: your own projects, projects shared with you, and every project in teams you administer.
Shared query parameters
Section titled “Shared query parameters”| Parameter | Type | Description |
|---|---|---|
project_id | int | Limit to a single project. Omit to aggregate across every call project you can see |
team | int | Team id, for team-scoped access. Ignored if you are not a member of that team |
start_date | date | Start of the window, YYYY-MM-DD (inclusive) |
end_date | date | End of the window, YYYY-MM-DD (inclusive, through 23:59:59) |
date_range | string | Named preset instead of explicit dates: mtd, last_month, last_30_days, last_90_days, ytd |
project_id and team apply to every endpoint on this page. The date parameters apply to the report, the best practices, the PDF export and the calls list; the detail, analysis-status, custom-questions and recluster endpoints are project-scoped and ignore them.
date_range wins when both it and explicit dates are sent. With no date parameters at all, the whole history is returned — unlike the web report, which defaults to the last 30 days.
Days and months start at midnight in the time zone set in the user’s profile when you call with a session cookie, as in the web app. Requests made with an API key use UTC.
GET /calls/api/report/
Section titled “GET /calls/api/report/”The aggregated report for the selected projects and window.
Additional query parameter:
| Parameter | Type | Description |
|---|---|---|
exemplary_limit | int | Longest exemplary_calls list to return, 1–50. Defaults to 5; a value out of range falls back to the default |
granularity | string | Bucket size of trend: day, week or month. Defaults to week; any other value returns 400 |
agent | int | Uspeech agent id, for that agent’s personal report |
Response (200 OK) — abridged, with long arrays cut to one entry:
{ "scope": "team", "agent_name": null, "date_range": { "start": "2026-05-01T00:00:00+00:00", "end": "2026-07-30T00:00:00+00:00", "preset": "last_90_days", "previous_start": "2026-01-31", "previous_end": "2026-04-30" }, "total_calls_all_time": 57, "unanalyzed_calls": 0, "headline": { "total_calls": 57, "analyzed_hours": 7.3, "analyzed_seconds": 26280, "average_score": 74.2, "weighted_compliance": 78.4, "scored_calls": 57, "critical_error_pct": 7.0, "negative_sentiment_pct": 32.5, "goal_reached_pct": 75.0, "calls_with_metadata": 57 }, "scorecard": [ { "criterion_id": "verification", "name": "Identity verification", "section": "Opening", "weight_pct": 15.4, "average_pct": 75.4, "previous_pct": 71.0, "delta_pct": 4.4, "critical_errors": 0, "calls": 40, "evaluated_calls": 31, "not_applicable_calls": 9 } ], "trend": [ { "period": "2026-06-29", "calls": 10, "average_score": 65.0, "negative_sentiment_pct": 30.0 } ], "contact_reasons": [ { "topic": "Billing dispute", "calls": 8, "volume_pct": 20.0 } ], "agents": [ { "agent": "Ana Diaz", "agent_id": 1, "calls": 26, "average_score": 72.7, "critical_error_pct": 7.7, "negative_sentiment_pct": 50.0, "goal_reached_pct": 76.9 } ], "exemplary_calls": [ { "id": 31, "file_id": 461, "file_name": "call_030.mp3", "call_datetime": "2026-07-21T10:39:32Z", "agent": "Ana Diaz", "direction": "inbound", "campaign": "Retention", "topic": "Billing dispute", "sentiment": "positive", "score_percentage": 100.0, "has_critical_error": false, "mistake_count": null, "missing_prompt_count": null, "goal_reached": true, "evaluated_score_pct": 100.0, "criteria_evaluated": 8, "criteria_total": 9, "strengths": ["Identity verification", "Adherence to the resolution script", "Objection handling and tone"] } ], "shifts": [ { "shift": "day", "total_calls": 46, "average_score": 74.8, "calls_with_metadata": 46 } ], "shift_hours": { "day_start": 8, "day_end": 20 }}Reading the sections:
| Field | Meaning |
|---|---|
scope, agent_name | team and null, or agent and the agent’s name for a personal report |
total_calls_all_time | Calls in scope before the date filter. When headline.total_calls is 0 and this is not, your window is simply wrong |
unanalyzed_calls | Transcribed calls in the window that no analysis has covered yet, typically uploaded while automatic analysis was off. They are not part of any other figure. Calls queued for automatic analysis are not counted |
headline | Volume and quality summary for the window. average_score is the plain mean of call scores; weighted_compliance is total points over total possible points, so long rubrics don’t get diluted. analyzed_hours is rounded to a tenth of an hour; analyzed_seconds is the exact audio length |
scorecard | One row per rubric criterion. previous_pct and delta_pct compare against the previous period in date_range.previous_start–previous_end: as many whole months before when the window is whole calendar months, the same days of the previous month when it starts on the 1st inside one month, and otherwise a window of the same length just before. They are null for an open-ended window, and for a criterion with no scores in the previous period. not_applicable_calls counts the calls where the criterion was skipped and awarded full points; those calls are included in average_pct, so a criterion with a high not_applicable_calls reads high because it rarely applied. evaluated_calls + not_applicable_calls is less than calls when the window includes calls analyzed before Uspeech recorded applicability |
trend | Buckets of granularity size, period being the first day of each — the Monday for weeks |
contact_reasons | Top reasons by volume. A trailing row with an empty topic and an other_topics count is the “everything else” bucket |
agents | Per-agent rollup. agent_id is Uspeech’s internal agent id — the one to pass to the explorer’s agent filter — not your own agent_id from the metadata |
exemplary_calls | The window’s best calls, best first: the Exemplary calls section of the report. Each entry is an explorer row plus evaluated_score_pct (the score on the criteria that applied), criteria_evaluated of criteria_total criteria applied, and up to three strengths — the heaviest criteria met in full. At most exemplary_limit calls and at most two per agent; the list is never padded, so it can be shorter or empty |
shifts | Same shape as headline plus shift (day / night). Only calls with a real call date/time are classified |
shift_hours | The day-shift window used, from the project’s settings |
Percentage fields are null rather than 0 when nothing in the window could be measured — no scored calls, no sentiment, no known outcome.
goal_reached_pct and every goal_reached field come from the rubric’s goal of the call criterion when the rubric has one, and from Calls Analysis otherwise.
Example:
curl -H "Authorization: Api-Key $USPEECH_KEY" \ "https://app.uspeech.io/calls/api/report/?project_id=312&date_range=last_30_days"import osimport requests
BASE_URL = "https://app.uspeech.io"HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}
report = requests.get( f"{BASE_URL}/calls/api/report/", headers=HEADERS, params={"project_id": 312, "date_range": "last_30_days"}, timeout=60,).json()print(report["headline"])const BASE_URL = 'https://app.uspeech.io';const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };
const params = new URLSearchParams({ project_id: '312', date_range: 'last_30_days' });const report = await fetch(`${BASE_URL}/calls/api/report/?${params}`, { headers: HEADERS,}).then((r) => r.json());console.log(report.headline);Personal reports for one agent
Section titled “Personal reports for one agent”Add agent to the report or the PDF to get one agent’s personal report instead of the team’s: the same report an agent with their own login sees. Use it to check what an agent sees, or to send them their PDF.
curl -H "Authorization: Api-Key $USPEECH_KEY" \ "https://app.uspeech.io/calls/api/report/?agent=59&date_range=last_30_days"agent is Uspeech’s internal id, from agents[].agent_id in the team report. Every figure then covers that agent’s calls only, and the response differs in these fields:
| Field | Team report | Personal report |
|---|---|---|
scope | team | agent |
agent_name | null | The agent’s name |
agents | Per-agent rollup | Empty |
unanalyzed_calls | Count for the window | 0 |
The PDF has its own narrative, written to the agent from their own figures, and leaves out the agent table and best practices.
| Status | When |
|---|---|
400 | agent is not a number |
404 | The agent has no calls in the projects you can see |
GET /calls/api/calls/
Section titled “GET /calls/api/calls/”A paginated, filterable table of analyzed calls, spanning every analysis batch in the selected projects.
Additional query parameters:
| Parameter | Type | Description |
|---|---|---|
agent | int / none | Uspeech agent id (from the report’s agents[].agent_id), or none for calls with no agent |
sentiment | string | positive, neutral or negative |
direction | string | inbound or outbound |
critical | bool | true returns only calls with a critical error |
exemplary | bool | true returns only the calls that meet the exemplary bar, best first, and ignores ordering. Unlike the report’s exemplary_calls, it is not capped per agent or by exemplary_limit |
search | string | Matches file name, topic, contact reason, caller number or campaign |
ordering | string | call_datetime, score_percentage, mistake_count or agent__name, optionally prefixed with -. Defaults to -call_datetime |
page | int | Page number; the page size is 25 |
Unknown values for sentiment, direction and ordering are ignored rather than rejected. Calls without a value for the sorted field — for example unscored calls when sorting by score_percentage — always come last, in both directions.
Response (200 OK):
{ "count": 57, "next": "https://app.uspeech.io/calls/api/calls/?page=2", "previous": null, "results": [ { "id": 28, "file_id": 458, "file_name": "call_027.mp3", "call_datetime": "2026-07-28T09:15:00Z", "agent": "Luis Gomez", "direction": "inbound", "campaign": "Retention", "topic": "Address change", "sentiment": "positive", "score_percentage": 66.3, "has_critical_error": false, "mistake_count": 0, "missing_prompt_count": 1, "goal_reached": true } ]}goal_reached is true, false or null when unknown. id is the call’s id for the detail endpoint below; file_id is the uploaded file, which is what the Uploading Recordings and Call Metadata endpoints use. topic is the codified contact reason once grouping has run, and the raw extracted topic before that.
Example — the worst-scoring inbound calls of the month:
curl -H "Authorization: Api-Key $USPEECH_KEY" \ "https://app.uspeech.io/calls/api/calls/?date_range=mtd&direction=inbound&ordering=score_percentage"calls = requests.get( f"{BASE_URL}/calls/api/calls/", headers=HEADERS, params={ "date_range": "mtd", "direction": "inbound", "ordering": "score_percentage", }, timeout=60,).json()for call in calls["results"]: print(call["file"], call["score_percentage"])const params = new URLSearchParams({ date_range: 'mtd', direction: 'inbound', ordering: 'score_percentage',});const calls = await fetch(`${BASE_URL}/calls/api/calls/?${params}`, { headers: HEADERS,}).then((r) => r.json());for (const call of calls.results) console.log(call.file, call.score_percentage);GET /calls/api/calls/{id}/
Section titled “GET /calls/api/calls/{id}/”Everything known about one call, merged across analysis types.
Response (200 OK):
{ "record": { "id": 28, "file_id": 458, "file_name": "call_027.mp3", "call_datetime": "2026-07-28T09:15:00Z", "call_datetime_source": "manifest", "agent": "Luis Gomez", "direction": "inbound", "campaign": "Retention", "caller_number": "+34600111222", "ended_by": "customer", "topic": "Address change", "sentiment": "positive", "score_percentage": 66.3, "total_points": 19.89, "max_possible_points": 30.0, "has_critical_error": false, "mistake_count": 0, "missing_prompt_count": 1, "goal_reached": true }, "copc": { "…": "per-criterion scores, justifications and quotes" }, "no_protocol": { "…": "detected mistakes and missed prompts" }, "custom_questions": { "…": "answers to the project's custom questions" }}record is the explorer row plus the caller number, who hung up first (ended_by: customer, agent or "" when unknown), the raw point totals and call_datetime_source. The other three keys carry the free-text output of each analysis type and are null when that analysis has not run for this call. Their internal structure follows the analysis result format and is best inspected against a real call.
Each entry in copc.criterion_scores carries an applicability field — "evaluated" or "not_applicable":
{ "criterion_id": "closing_summary", "justification": "The customer hung up before the agent could summarize the agreement.", "quote": "[04:12] Customer: I have to go — goodbye.", "applicability": "not_applicable", "score": 15, "max_points": 15, "is_critical_error": false}A criterion that did not apply is awarded its full max_points, so it is indistinguishable from a perfect score on score alone — applicability is the only field that separates them. A closing step excused because the customer hung up before the agent’s goodbye also carries "override": "customer_hangup" — see Closing steps when the customer hangs up. If you compute your own per-criterion averages, filter out not_applicable rows first; otherwise a conditional criterion reads high simply because it rarely applied. See How Scoring Works.
Errors: 404 when the call does not exist or belongs to a project you cannot see.
GET /calls/api/analysis-status/
Section titled “GET /calls/api/analysis-status/”Progress of automatic analysis for the selected projects — designed for polling while uploads are being processed.
Response (200 OK):
{ "analysis_status": { "calls_analysis_copc": { "completed": 54, "queued": 3 }, "calls_analysis_no_protocol": { "completed": 57 } }, "analyzed_calls": 57, "duplicate_uploads": 2, "in_progress": true, "reclustering": false, "last_analyzed_at": "2026-07-29T02:50:11.127124+00:00"}| Field | Meaning |
|---|---|
analysis_status | Per analysis type, a count of calls in each state (queued, processing, completed, failed) |
analyzed_calls | Calls with results, ignoring any date filter. A call that only has metadata is not counted until it is analyzed |
duplicate_uploads | Files uploaded under a name the project already had. They are the same call, so a record replaces its predecessor — which is why the file count can run ahead of the call count |
in_progress | true while any analysis is queued or processing — poll until it is false, then re-fetch the report |
reclustering | true while contact reasons are being re-grouped |
last_analyzed_at | Timestamp of the most recent result, or null |
while :; do resp=$(curl -sS "https://app.uspeech.io/calls/api/analysis-status/?project_id=312" \ -H "Authorization: Api-Key $USPEECH_KEY") [ "$(echo "$resp" | jq -r .in_progress)" = "false" ] && break sleep 30doneimport time
while True: status = requests.get( f"{BASE_URL}/calls/api/analysis-status/", headers=HEADERS, params={"project_id": 312}, timeout=30, ).json() if not status["in_progress"]: break time.sleep(30)const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
while (true) { const status = await fetch( `${BASE_URL}/calls/api/analysis-status/?project_id=312`, { headers: HEADERS }, ).then((r) => r.json()); if (!status.in_progress) break; await sleep(30_000);}See Uploading Recordings for the full upload-then-poll walkthrough.
GET /calls/api/custom-questions/
Section titled “GET /calls/api/custom-questions/”Per-call answers to the project’s custom questions, gathered across batches.
Response (200 OK):
{ "questions": ["Was a callback offered?", "Was the discount mentioned?"], "calls": [ { "call_analysis_id": 904, "file": "call_027.mp3", "call_datetime": "2026-07-28T09:15:00Z", "agent": "Luis Gomez", "answers": { "Was a callback offered?": { "answer": "Yes — agent offered a callback for Tuesday.", "quotes": 2 } } } ], "count": 12}questions is the union of questions seen across the returned calls, in first-seen order — use it as the column list. A call that was analyzed under an older question set simply has no entry for the newer questions. quotes counts the supporting transcript quotes behind the answer.
Projects without custom questions return empty arrays and count: 0.
POST /calls/api/recluster/
Section titled “POST /calls/api/recluster/”Re-group open-ended contact reasons on demand, the same action as Refresh contact reasons in the report.
Reclustering is queued for every accessible open-ended project; projects with frozen predefined codes classify each call on arrival and are skipped, so they never appear in the response. The work runs in the background — poll analysis-status for reclustering to see when it finishes.
Response (202 Accepted):
{ "reclustering": [312, 318], "count": 2 }reclustering lists the project ids that were queued. Overlapping requests are de-duplicated, so calling this while a recluster is already running is harmless.
Example:
curl -X POST -H "Authorization: Api-Key $USPEECH_KEY" \ "https://app.uspeech.io/calls/api/recluster/?project_id=312"response = requests.post( f"{BASE_URL}/calls/api/recluster/", headers=HEADERS, params={"project_id": 312}, timeout=30,)response.raise_for_status()const response = await fetch( `${BASE_URL}/calls/api/recluster/?project_id=312`, { method: 'POST', headers: HEADERS },);if (!response.ok) throw new Error(await response.text());GET /calls/api/report/best-practices/
Section titled “GET /calls/api/report/best-practices/”The best practices drawn from the report’s exemplary calls: three to five behaviors other agents should copy, each with a quote from the call it came from.
Takes the shared query parameters and exemplary_limit, exactly like the report, and works on the same exemplary calls the report returns for them. Generation takes a few minutes, so it never happens on GET: you start it with POST and poll.
Response (200 OK):
{ "status": "ready", "practices": [ { "title": "Confirm the customer's identity before discussing the account", "description": "The agent asks for the full name and the tracking number before giving any shipment detail. It protects the customer and avoids talking to the wrong person.", "quote": "Speaker Ana: Could I have your full name, please?\nSpeaker 2: Laura Medina.\nSpeaker Ana: Thank you. And the tracking number?", "turns": [ { "speaker": "Ana", "text": "Could I have your full name, please?" }, { "speaker": "2", "text": "Laura Medina." }, { "speaker": "Ana", "text": "Thank you. And the tracking number?" } ], "call_id": 31, "file_name": "call_030.mp3", "agent": "Ana Diaz", "call_datetime": "2026-07-21T10:39:32+00:00" } ]}status | Meaning |
|---|---|
none | Nothing generated yet for these calls. POST to start |
pending | Generation is running. Poll every few seconds |
ready | practices holds the result |
failed | Generation failed, or has been pending for more than about 25 minutes. POST again to retry |
unavailable | No call in the window meets the exemplary bar, so there is nothing to learn from |
practices is null unless status is ready. quote is copied word for word from the call; turns splits it into dialogue turns. speaker is the name the transcript gives, or a number when the speakers could not be told apart. call_id is the id for the call detail endpoint.
A result is kept per set of exemplary calls and per language. When the list changes — another window, another exemplary_limit, or a call re-analyzed — the status goes back to none for the new set. Practices are written in English unless you send Accept-Language: es; quotes stay in the language of the call.
POST /calls/api/report/best-practices/
Section titled “POST /calls/api/report/best-practices/”Starts generating best practices for the same calls. No request body.
Response: 202 Accepted with {"status": "pending", "practices": null} when generation starts. When a result already exists or is already being generated, nothing new starts and you get 200 OK with the current state; an unavailable window returns 200 OK as well. A failed result is retried.
URL="https://app.uspeech.io/calls/api/report/best-practices/?project_id=312&date_range=last_30_days"curl -sS -X POST -H "Authorization: Api-Key $USPEECH_KEY" "$URL"while :; do resp=$(curl -sS -H "Authorization: Api-Key $USPEECH_KEY" "$URL") [ "$(echo "$resp" | jq -r .status)" != "pending" ] && break sleep 15doneecho "$resp" | jq '.practices[].title'import time
params = {"project_id": 312, "date_range": "last_30_days"}url = f"{BASE_URL}/calls/api/report/best-practices/"state = requests.post(url, headers=HEADERS, params=params, timeout=30).json()while state["status"] == "pending": time.sleep(15) state = requests.get(url, headers=HEADERS, params=params, timeout=30).json()for practice in state["practices"] or []: print(practice["title"], "—", practice["agent"])const params = new URLSearchParams({ project_id: '312', date_range: 'last_30_days' });const url = `${BASE_URL}/calls/api/report/best-practices/?${params}`;let state = await fetch(url, { method: 'POST', headers: HEADERS }).then((r) => r.json());while (state.status === 'pending') { await new Promise((resolve) => setTimeout(resolve, 15_000)); state = await fetch(url, { headers: HEADERS }).then((r) => r.json());}for (const practice of state.practices ?? []) console.log(practice.title, '—', practice.agent);GET /calls/api/report/pdf/
Section titled “GET /calls/api/report/pdf/”The same client-ready PDF the report’s Export PDF button produces, including the AI-written executive summary, for the current filters.
Accepts exemplary_limit like the report, and agent for one agent’s personal PDF; its exemplary calls section lists the same calls. Best practices are included only when they have already been generated for those calls and that language — the PDF never generates them, so POST to the best-practices endpoint and wait for ready first if you want them in the document.
Response (200 OK): application/pdf as a file download. Generation runs synchronously and includes an LLM call for the narrative sections, so expect this to take noticeably longer than the JSON endpoint; if the narrative fails, the PDF is still returned with its tables and a note.
The document is written in English by default. Send Accept-Language: es for Spanish — a key-authenticated request has no browser session, so the language preference on the user’s profile does not apply here.
Example:
curl -H "Authorization: Api-Key $USPEECH_KEY" \ -o call_report.pdf \ "https://app.uspeech.io/calls/api/report/pdf/?project_id=312&date_range=last_month"response = requests.get( f"{BASE_URL}/calls/api/report/pdf/", headers=HEADERS, params={"project_id": 312, "date_range": "last_month"}, timeout=600,)response.raise_for_status()with open("call_report.pdf", "wb") as fh: fh.write(response.content)import { writeFile } from 'node:fs/promises';
const params = new URLSearchParams({ project_id: '312', date_range: 'last_month' });const response = await fetch(`${BASE_URL}/calls/api/report/pdf/?${params}`, { headers: HEADERS,});if (!response.ok) throw new Error(await response.text());await writeFile('call_report.pdf', Buffer.from(await response.arrayBuffer()));Errors
Section titled “Errors”| Status | When |
|---|---|
401 / 403 | Missing, malformed, revoked or inactive-user API key |
404 | On the report, best-practices and PDF endpoints, project_id names a project that does not exist or is not visible to you; on the detail endpoint, the same for the call itself |
Note the asymmetry: an unreachable project_id is a 404 on the report, the best practices and the PDF, but on the list, status, custom-questions and recluster endpoints it simply matches nothing and you get an empty, zeroed result. An empty result is never an error in itself — a project you can see with no analyzed calls looks the same. See Status Codes & Errors for the general error shape.