> For a complete documentation index, fetch https://docs.voximplant.ai/llms.txt

# GetCallHistory

POST https://api.voximplant.com/platform_api/GetCallHistory

Gets the account's call history (including call duration, cost, logs and other call information). You can filter the call history by a certain date.

Allowed roles: `Owner`, `Admin`, `Developer`, `Supervisor`, `Support`.

**Example request:** Get the first call session history record with calls and record URLs from the 2020-02-25 00:00:00 UTC to the 2020-02-26 00:00:00 UTC.

Reference: https://docs.voximplant.ai/api-reference/management-api/reference/history/get-call-history

## Authentication

- `Authorization` header (bearer token, required) — Voximplant Management API uses signed JWT tokens generated from your service-account private key. Pass the token in the `Authorization` header as a Bearer value: ``` Authorization: Bearer $VOXIMPLANT_TOKEN ``` See [Authorization](/api-reference/management-api/authorization) for ready-to-copy snippets in bash, Python, Node.js and Go that turn your `credentials.json` into a token.

## Request

### Query parameters

- `from_date` (string, required) — The from date in the selected timezone in 24-h format: YYYY-MM-DD HH:mm:ss
- `to_date` (string, required) — The to date in the selected timezone in 24-h format: YYYY-MM-DD HH:mm:ss
- `call_session_history_id` (list of integer, optional) — To get the call history for the specific sessions, pass the session IDs to this parameter separated by a semicolon (;). The maximum number of records is 1000. You can find the session ID in the AppEvents.Started event's **sessionID** property in a scenario, or retrieve it from the **call\_session\_history\_id** value returned from the StartScenarios or StartConference methods
- `application_id` (integer, optional) — To receive the call history for a specific application, pass the application ID to this parameter
- `application_name` (string, optional) — The application name, can be used instead of **application_id**
- `user_id` (list of integer, optional) — To receive the call history for a specific users, pass the user ID list separated by semicolons (;). If it is specified, the output contains the calls from the listed users only
- `rule_name` (string, optional) — To receive the call history for a specific routing rule, pass the rule name to this parameter. Applies only if you set application_id or application_name
- `remote_number` (list of string, optional) — To receive a call history for a specific remote numbers, pass the number list separated by semicolons (;). A remote number is a number on the client side. Ignored if the `remote_number_list` parameter is not empty
- `remote_number_list` (map from string to any, optional) — A JS array of strings of specific remote phone numbers to sort the call history. Has higher priority than the `remote_number` parameter. If the array is empty, the `remote_number` parameter is used instead
- `local_number` (list of string, optional) — To receive a call history for a specific local numbers, pass the number list separated by semicolons (;). A local number is a number on the platform side
- `call_session_history_custom_data` (string, optional) — To filter the call history by the custom_data passed to the call sessions, pass the custom data to this parameter
- `with_calls` (boolean, optional, default: false) — Whether to receive a list of sessions with all calls within the sessions, including phone numbers, call cost and other information
- `with_records` (boolean, optional, default: false) — Whether to get the calls' records
- `with_other_resources` (boolean, optional, default: true) — Whether to get other resources usage (see [ResourceUsageType])
- `child_account_id` (list of integer, optional) — The child account ID list separated by semicolons (;)
- `children_calls_only` (boolean, optional, default: false) — Whether to get the children account calls only
- `desc_order` (boolean, optional, default: false) — Whether to get records in the descent order
- `with_total_count` (boolean, optional, default: true) — Whether to include the 'total_count' and increase performance
- `count` (integer, optional, default: 20) — The number of returning records. The maximum value is 1000
- `offset` (integer, optional, default: 0) — The number of records to skip in the output. The maximum value of 10000

## Response

### 200

Successful response

- `result` (list of CallSessionInfoType, optional) — The CallSessionInfoType records
- `total_count` (integer, optional) — The total found call session count
- `count` (integer, optional) — The returned call session count
- `timezone` (string, optional) — The used timezone

## Types

### CallSessionInfoType

The [GetCallHistory] function result item.

- `audio_quality` (string, optional) — Call's audio quality. The possible values are: Standard | HD | Ultra HD.
- `rule_name` (string, optional) — Routing rule name
- `application_name` (string, optional) — Application name
- `call_session_history_id` (integer, optional) — Unique JS session identifier
- `account_id` (integer, optional) — Account ID that initiates the JS session
- `application_id` (integer, optional) — Application ID that initiates the JS session
- `user_id` (integer, optional) — User ID that initiates the JS session
- `start_date` (string, optional) — Timestamp in YYYY-MM-DD HH:mm:ss format. Start date in the selected timezone in 24-h format: YYYY-MM-DD HH:mm:ss
- `duration` (integer, optional) — Entire JS session duration in seconds. The session can contain multiple calls
- `initiator_address` (string, optional) — Initiator's IP address
- `media_server_address` (string, optional) — Media server IP address
- `log_file_url` (string, optional) — Link to the session log. The log retention policy is 1 month, after that time this field clears. If you have issues accessing the log file, check if the application has "Secure storage of applications and logs" feature enabled. In this case, you need to authorize.
- `finish_reason` (string, optional) — Finish reason. Possible values are __Normal termination__, __Insufficient funds__, __Internal error (billing timeout)__, __Terminated administratively__, __JS session error__, __Timeout__
- `calls` (list of CallInfoType, optional) — Calls within the JS session, including durations, cost, phone numbers and other information
- `other_resource_usage` (list of ResourceUsageType, optional) — Used resources
- `records` (list of RecordType, optional) — Bound records
- `custom_data` (string, optional) — Custom data
- `active` (boolean, optional)

### CallInfoType

The call info.

- `call_id` (integer, optional) — Call's history ID
- `start_time` (string, optional) — Timestamp in YYYY-MM-DD HH:mm:ss format. Call start time in the selected timezone in 24-h format: YYYY-MM-DD HH:mm:ss
- `diversion_number` (string, optional) — Call forwarding number
- `duration` (integer, optional) — Call duration in seconds
- `local_number` (string, optional) — Local number on the platform side
- `remote_number` (string, optional) — Remote number on the client side
- `remote_number_type` (string, optional) — Type of the remote number, e.g., a PSTN, mobile, user or sip address
- `incoming` (boolean, optional) — Whether the call is incoming
- `successful` (boolean, optional) — Whether the call is successful
- `transaction_id` (integer, optional) — Transaction ID
- `record_url` (string, optional) — Record URL
- `media_server_address` (string, optional) — Media server's IP address
- `cost` (double, optional) — Call's cost
- `custom_data` (string, optional) — Custom data passed to the JS session
- `end_reason` (CallInfoTypeEndReason, optional) — End reason code and description
- `audio_quality` (string, optional)
- `direction` (string, optional)

### ResourceUsageType

The resource usage info.

- `resource_usage_id` (integer, optional) — The resource usage ID
- `resource_type` (string, optional) — The resource type. The possible values are CALLSESSION, VIDEOCALL, VIDEORECORD, VOICEMAILDETECTION, ASR, TRANSCRIPTION, TTS_TEXT_GOOGLE, AUDIOHDCONFERENCE
- `cost` (double, optional) — The resource cost
- `description` (string, optional) — The description
- `used_at` (string, optional) — Timestamp in YYYY-MM-DD HH:mm:ss format. The start resource using time in the selected timezone in 24-h format: YYYY-MM-DD HH:mm:ss
- `transaction_id` (integer, optional) — The transaction ID
- `resource_quantity` (integer, optional) — The resource quantity
- `unit` (string, optional) — The resource unit
- `ref_call_id` (integer, optional) — The reference to call

### RecordType

The record info.

- `record_id` (integer, optional) — The record ID
- `record_name` (string, optional) — The record name
- `cost` (double, optional) — The record cost
- `start_time` (string, optional) — Timestamp in YYYY-MM-DD HH:mm:ss format. The start recording time in the selected timezone in 24-h format: YYYY-MM-DD HH:mm:ss
- `duration` (integer, optional) — The call duration in seconds
- `record_url` (string, optional) — The record URL. If you have issues accessing the record file, check if the application has "Secure storage of applications and logs" feature enabled. In this case, you need to authorize.
- `transaction_id` (integer, optional) — The transaction ID
- `file_size` (double, optional) — The file size
- `transcription_url` (string, optional) — Transcription URL. To open the URL, please add authorization parameters and **record_id** to it
- `transcription_status` (string, optional) — The status of transcription. The possible values are Not required, In progress, Complete
- `hd_audio` (boolean, optional)
- `transcription_transaction_id` (integer, optional)
- `is_removed` (boolean, optional)
- `lossless` (boolean, optional)
- `expiration_date` (string, optional)
- `media_parameters` (string, optional)

### CallInfoTypeEndReason

End reason code and description

- `code` (integer, optional)
- `details` (string, optional)

## Examples

**Response**

```json
{
  "result": [
    {
      "rule_name": "incoming",
      "application_name": "app.account.voximplant.com",
      "call_session_history_id": 4202753936,
      "account_id": 4714487,
      "application_id": 10733204,
      "start_date": "2024-05-29 15:05:26",
      "duration": 6,
      "initiator_address": "1.1.1.1",
      "media_server_address": "2.2.2.2",
      "log_file_url": "https://storage-gw-ru-02.voximplant.com/voximplant-logs-secure/2024/05/29/very-beautiful-link?sessionid=4881753936",
      "finish_reason": "Normal termination",
      "calls": [
        {
          "call_id": 4202571214,
          "start_time": "2024-05-29 15:05:27",
          "diversion_number": "",
          "duration": 6,
          "local_number": "420214575",
          "remote_number": "42027877410",
          "remote_number_type": "pstn",
          "incoming": true,
          "successful": true,
          "transaction_id": 42027707220008,
          "record_url": "https://storage-gw-ru-02.voximplant.com/voximplant-records-secure/2024/05/29/very-beautiful-record.mp3?record_id=4124252234",
          "cost": 0.530625,
          "end_reason": {
            "code": 200,
            "details": "Normal call clearing"
          },
          "audio_quality": "Standard",
          "direction": "All numbers"
        }
      ],
      "other_resource_usage": [
        {
          "resource_usage_id": 4202424788,
          "cost": 0.0096,
          "description": "TextToSpeech",
          "used_at": "2024-05-29 15:05:27",
          "transaction_id": 42027707260008,
          "resource_quantity": 36,
          "unit": ""
        },
        {
          "resource_usage_id": 4202424789,
          "resource_type": "TRANSCRIPTION",
          "cost": 0.108,
          "description": "Call Transcription",
          "used_at": "2024-05-29 15:05:27",
          "transaction_id": 42027706800008,
          "resource_quantity": 5,
          "unit": ""
        }
      ],
      "records": [
        {
          "record_id": 4202252234,
          "record_name": "Call Recorder",
          "cost": 0.053063,
          "start_time": "2024-05-29 15:05:26",
          "duration": 5,
          "record_url": "https://storage-gw-ru-02.voximplant.com/voximplant-records-secure/2024/05/29/very-beautiful-record.mp3?record_id=4202252234",
          "transaction_id": 42027706770008,
          "file_size": 0,
          "transcription_url": "https://storage-gw-ru-02.voximplant.com/voximplant-records-secure/2024/05/29/very-beautiful-link",
          "transcription_status": "Complete",
          "hd_audio": false,
          "transcription_transaction_id": 42027706800008,
          "is_removed": false,
          "lossless": false,
          "expiration_date": "2024-08-27",
          "media_parameters": "{\"audio_codec\" : \"mp3\", \"container\" : \"mp3\"}"
        }
      ],
      "active": false
    }
  ],
  "total_count": 1,
  "count": 1,
  "timezone": "Etc/GMT"
}
```

**SDK Code**

```python Example 1
import requests

url = "https://api.voximplant.com/platform_api/GetCallHistory"

querystring = {"from_date":"2026-04-28 17:30:00","to_date":"2026-04-28 17:30:00"}

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Example 1
const url = 'https://api.voximplant.com/platform_api/GetCallHistory?from_date=2026-04-28+17%3A30%3A00&to_date=2026-04-28+17%3A30%3A00';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Example 1
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.voximplant.com/platform_api/GetCallHistory?from_date=2026-04-28+17%3A30%3A00&to_date=2026-04-28+17%3A30%3A00"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Example 1
require 'uri'
require 'net/http'

url = URI("https://api.voximplant.com/platform_api/GetCallHistory?from_date=2026-04-28+17%3A30%3A00&to_date=2026-04-28+17%3A30%3A00")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Example 1
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.voximplant.com/platform_api/GetCallHistory?from_date=2026-04-28+17%3A30%3A00&to_date=2026-04-28+17%3A30%3A00")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Example 1
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.voximplant.com/platform_api/GetCallHistory?from_date=2026-04-28+17%3A30%3A00&to_date=2026-04-28+17%3A30%3A00', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Example 1
using RestSharp;

var client = new RestClient("https://api.voximplant.com/platform_api/GetCallHistory?from_date=2026-04-28+17%3A30%3A00&to_date=2026-04-28+17%3A30%3A00");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Example 1
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.voximplant.com/platform_api/GetCallHistory?from_date=2026-04-28+17%3A30%3A00&to_date=2026-04-28+17%3A30%3A00")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```