Retrieve call statistics
curl --fail-with-body -X GET 'https://api.talki.it/v1/calls/stats?days=30' \ -H "Authorization: Bearer $TALKI_API_KEY"from talki import Talki
talki = Talki()
call_stats = talki.calls.get_stats(days=30)print(call_stats)import { Talki } from "@hubtec/talki";
const talki = new Talki();
const callStats = await talki.calls.getStats({ days: 30 });console.log(callStats);Return totals, the daily series and the top callers over the last days, or over the local days from to to (at most 366). Requires calls:read. Limited to 600 requests per minute per account (API key) or per installation (OAuth).
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters”Header Parameters
Section titled “Header Parameters”Example
2026-10-01Serve this one request at the given dated contract version instead of the credential’s pin. An unsupported value is refused with 400 unsupported_version, never downgraded.
Responses
Section titled “ Responses ”Successful Response
Call figures over a period (the last days, or the local days from to to), plus today, this week and this month, in the account’s timezone.
object
How many days the period covers: days, or the days from from to to.
Start of the period, RFC 3339 UTC, included.
End of the period, RFC 3339 UTC, excluded: now, or local midnight after to.
Calls in the period.
Their total talk time, as billed (Call.duration_seconds).
Their average talk time, to one decimal. 0 with no calls.
Calls in the period that booked at least one appointment, counted once however many they booked, and still counted if the booking was cancelled since.
Calls in the period that left at least one question the assistant could not answer (GET /v1/unresolved_requests), counted once however many they left, whatever the requests’ status now. A call may count here and in booked_calls both. Calls Talki refused are never in these figures: see GET /v1/refused_calls/summary.
Calls in the period the assistant transferred to a person, counted once however many transfers they had. Calls recorded before transfers were stored (see Call.outcome) are not counted, so a period reaching back before then undercounts.
Calls since midnight today.
Calls since Monday.
Calls since the first of the month.
One entry per day in the period that had calls, oldest first.
One day of the period’s series.
object
A local calendar day in the account’s timezone, YYYY-MM-DD.
Calls that started that day.
Their total talk time.
Up to ten numbers that called most in the period, most calls first.
One of the numbers that called most in the period.
Example
{ "period_days": 30, "period_start": "2026-09-07T22:00:00Z", "period_end": "2026-10-07T22:00:00Z", "total_calls": 142, "total_duration_seconds": 21480, "average_duration_seconds": 151.3, "booked_calls": 61, "unresolved_calls": 9, "transferred_calls": 7, "today": 4, "this_week": 23, "this_month": 38, "daily": [ { "date": "2026-10-07", "calls": 4, "duration_seconds": 612 } ], "top_callers": [ { "phone_number": "+393331234567", "calls": 5, "duration_seconds": 840, "last_call_at": "2026-10-07T08:41:09Z" } ]}Headers
Section titled “Headers”Identifier to include when contacting Talki support.
Example
2026-10-01The dated contract version this response was served at.
A parameter, cursor, body field, or required idempotency key is invalid, or Talki-Version names an unsupported version (unsupported_version).
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "invalid_request", "code": "invalid_parameter", "message": "One or more request values are invalid.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The credential is missing, malformed, expired, revoked, or unknown.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "authentication_error", "code": "invalid_credentials", "message": "The supplied API credential is invalid.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The account does not have an active subscription.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "permission_error", "code": "subscription_inactive", "message": "This account does not have an active subscription.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The account or credential may not perform this request.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This credential does not have the required scope.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
location_id names no location of the authenticated account.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "invalid_request", "code": "resource_not_found", "message": "No such location.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The account or installation exceeded its request rate (rate_limit_exceeded), or the calling address did (ip_rate_limited).
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Retry after the interval in Retry-After.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
Seconds to wait before retrying.
The budget of the window that was exceeded. Absent on ip_rate_limited.
Requests left in the window. Absent on ip_rate_limited.
When the window resets, in Unix seconds. Absent on ip_rate_limited.
An unexpected error occurred.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected error occurred. Quote the request_id when reporting it.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.