AI agents voice sessions

Overview

Two functions return the voice call metrics of your AI Agents. They take the same parameters and return the same metrics:

ai_agents_voice_sessions_summary returns one row with the totals of the date range.
ai_agents_voice_sessions_timeseries returns one row for each day (UTC) that has calls.

Use them to count answered calls, to measure call time, and to split voicemail from other calls. The functions count one row for each conversation on Twilio Voice, Telnyx Voice, or Web Voice.

Quick start

This example returns the totals for one AI Agent over one week:

query VoiceSessionsSummary(
  $startDate: timestamp!
  $endDate: timestamp!
  $brainIds: _uuid
) {
  ai_agents_voice_sessions_summary(
    args: {
      start_time: $startDate
      end_time: $endDate
      brain_parent_ids: $brainIds
    }
  ) {
    total_voice_sessions
    call_duration_seconds
    call_duration_count
    voicemail_sessions
    voicemail_call_duration_seconds
    carrier_call_count
  }
}

Variables:

{
  "startDate": "2026-10-12",
  "endDate": "2026-10-18",
  "brainIds": "{a2wv9283-9b53-4d7b-b77d-2650f3a1a99c}"
}

Try it

Use the interactive playground below to test the query. Replace the variables with your own dates and AI Agent IDs.

Loading GraphQL Playground...

Parameters

Both functions take these parameters.

Parameter	Type	Description
`start_time`	`timestamp`	Required. First day of the range (format: `yyyy-mm-dd`)
`end_time`	`timestamp`	Required. Last day of the range (format: `yyyy-mm-dd`). The whole day is included
`account_id`	`uuid`	Optional. Defaults to the account of your API key
`desk_ids`	`_uuid`	Filter by environment IDs
`brain_parent_ids`	`_uuid`	Filter by AI Agent IDs
`channels`	`_text`	Filter by voice channel: `twilio-voice`, `telnyx-voice`, or `web-voice`
`is_proactive`	`Boolean`	`true` for outbound calls only, `false` for inbound calls only
`csat_brain`	`_int4`	Filter by the customer satisfaction score of the AI Agent
`is_test`	`Boolean`	`false` to leave out test calls. By default, test calls are included
`answered_only`	`Boolean`	Defaults to `true`, which counts answered calls only. Pass `false` to count every dialed call

The range covers whole days in UTC, from the day of start_time to the day of end_time. To get one day, pass the same date in both. The functions look back 189 days, so they return no call that started earlier.

Answered calls

The default, answered_only: true, counts a call only in these cases:

The other end sent at least one message.
The carrier reports that the call was answered. This also counts a person who picked up and said nothing.

Neither signal proves that a person answered. A call that went to voicemail also counts as answered. Dials that rang out, failed, or were rejected are left out.

Response fields

Field	Type	Description
`time_bucket`	`timestamp`	The day of the row (UTC). Only in `ai_agents_voice_sessions_timeseries`
`account_id`	`uuid`	Account identifier
`total_voice_sessions`	`Int`	Number of voice calls, voicemail included
`call_duration_seconds`	`bigint`	Total call time in seconds. See Call time
`call_duration_count`	`Int`	Number of calls in `call_duration_seconds`
`carrier_call_count`	`Int`	Number of calls whose time comes from the carrier's call record
`total_duration_seconds`	`bigint`	Total time from the start of each call to its last message, in seconds
`duration_count`	`Int`	Number of calls in `total_duration_seconds`
`voicemail_sessions`	`Int`	Number of calls that went to voicemail
`voicemail_call_duration_seconds`	`bigint`	The voicemail share of `call_duration_seconds`. `null` for a range without voicemail
`voicemail_duration_seconds`	`bigint`	The voicemail share of `total_duration_seconds`. `null` for a range without voicemail
`voicemail_duration_count`	`Int`	Number of voicemail calls in `voicemail_duration_seconds`

The Voicemail detection tool of the AI Agent marks a call as voicemail. The voicemail fields are part of the answered calls, so subtract them to get the other calls. For example, the average time of a call that did not go to voicemail is (total_duration_seconds - voicemail_duration_seconds) / (duration_count - voicemail_duration_count). In this formula, use 0 for a voicemail field that is null. If duration_count and voicemail_duration_count are equal, every call went to voicemail, and the average has no value.

Call time

call_duration_seconds uses the carrier's call time, from answer to hang-up. For a call that transfers to a human agent, the transfer leg is not added, because the first leg stays open for the whole call. A call without a carrier record uses the time from the start of the call to its last message. Web Voice calls have no carrier, so they always use that time.

total_duration_seconds always uses the time from the start of the call to its last message. It stops at the last message, not at the close of the conversation, because a voice conversation stays open for minutes after the call ends.

Each call is rounded to whole seconds before the sum. Neither field is rounded the way the carrier bills. For billable minutes, use list_voice_calls.

Empty results

ai_agents_voice_sessions_summary returns no row for a range without calls.
ai_agents_voice_sessions_timeseries returns no row for a day without calls. Fill the missing days with zeros in your own code.

Common use cases

Answered calls
Every dialed call
Outbound on Telnyx

Totals of the answered calls on one environment:

{
  "startDate": "2026-10-01",
  "endDate": "2026-10-31",
  "deskIds": "{d2be0283-9b53-4d7b-b77d-2650f3a1a99c}"
}

Every call, answered or not:

{
  "startDate": "2026-10-01",
  "endDate": "2026-10-31",
  "answeredOnly": false
}

Outbound calls on Telnyx Voice, without test calls:

{
  "startDate": "2026-10-01",
  "endDate": "2026-10-31",
  "channels": "{telnyx-voice}",
  "isProactive": true,
  "isTest": false
}

Example response

{
  "data": {
    "ai_agents_voice_sessions_summary": [
      {
        "account_id": "8fb5d9d4-c3f0-4165-a8e9-41655e0fe624",
        "total_voice_sessions": 513,
        "call_duration_seconds": 20454,
        "call_duration_count": 513,
        "carrier_call_count": 498,
        "total_duration_seconds": 19870,
        "duration_count": 511,
        "voicemail_sessions": 218,
        "voicemail_call_duration_seconds": 7957,
        "voicemail_duration_seconds": 7690,
        "voicemail_duration_count": 218
      }
    ]
  }
}

Full query reference

View the complete GraphQL query with all available fields

query VoiceSessionsSummary(
  $accountId: uuid
  $startDate: timestamp!
  $endDate: timestamp!
  $deskIds: _uuid
  $brainIds: _uuid
  $channels: _text
  $isProactive: Boolean
  $csatBrain: _int4
  $isTest: Boolean
  $answeredOnly: Boolean
) {
  ai_agents_voice_sessions_summary(
    args: {
      account_id: $accountId
      start_time: $startDate
      end_time: $endDate
      desk_ids: $deskIds
      brain_parent_ids: $brainIds
      channels: $channels
      is_proactive: $isProactive
      csat_brain: $csatBrain
      is_test: $isTest
      answered_only: $answeredOnly
    }
  ) {
    account_id
    total_voice_sessions
    call_duration_seconds
    call_duration_count
    carrier_call_count
    total_duration_seconds
    duration_count
    voicemail_sessions
    voicemail_call_duration_seconds
    voicemail_duration_seconds
    voicemail_duration_count
  }
}

For the daily rows, call ai_agents_voice_sessions_timeseries with the same arguments and add the time_bucket field.

Overview​

Quick start​

Try it​

Parameters​

Answered calls​

Response fields​

Call time​

Empty results​

Common use cases​

Example response​

Full query reference​