> For the complete documentation index, see [llms.txt](https://docs.talkstack.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talkstack.ai/call/get-call-history.md).

# Get call history

**Step 1: Prepare your request**

* **Endpoint:** `/call/get-call-history`
* **Method:** `POST`
* **URL:** `https://api.talkstackai.com/call/get-call-history`
* **Headers:** Include `Content-Type: application/json`.
* **Authorization:** Bearer token or x-api-key in headers

**Step 2: Create the Request Body**

* `projectId`: id of the project for which you want to fetch the call list.
* `pageSize`(optional): number of logs to be displayed in the call list. If pages is not defined default value, i.e., 20 is used. It is optional and defaults to 20.

```
{
    "projectId": "XXXXXXXXXXXXXXXXXXXXXXXXXX",
    "pageSize": 20
}
```

**Step 3: Filter using query params**

* `to`: filter the list to include the call made to a specific number.
* `from`: filter the list to include the call made from a specific number.
* `status`: filter the list to include the call with a specific status. The status value will be one of the following: `queued`, `initiated`, `ringing`, `in-progress`, `completed`, `busy`, `failed`, or `no-answer`.
* `startTime`: Only include calls that started on this date. Specify a date as `YYYY-MM-DD` in UTC, for example: `2009-07-06`, to read only calls that started on this date.
* `startTimeBefore`: Only include calls that started on or before midnight of this date. Specify a date as `YYYY-MM-DD` in UTC, for example `2009-07-06`.
* `startTimeAfter`: Only include calls that started on or after midnight of this date. Specify a date as `YYYY-MM-DD` in UTC, for example `2009-07-06`.
* `.endTime`: Only include calls that ended on this date. Specify a date as `YYYY-MM-DD` in UTC, for example `2009-07-06` .
* `endTimeBefore`: Only include calls that ended on or before midnight of this date. Specify a date as `YYYY-MM-DD` in UTC, for example `2009-0-06`.
* `.endTimeAfter`: Only include calls that ended on or after midnight of this date. Specify a date as `YYYY-MM-DD` in UTC, for example `2009-0-06`.

**Step 4: Handle the response**

The response will provide the list of calls associated with projectId and filtered using the query parameters.

**Success Response:**

* **Status Code:** `200 OK`
* **Body:** The response includes details like status, from, to, date, recordingUrls, and additional call data

```
[
    {
      "annotation": "billingreferencetag1",
      "answered_by": "machine_start",
      "api_version": "2010-04-01",
      "caller_name": "callerid1",
      "date_created": "Fri, 18 Oct 2019 17:00:00 +0000",
      "date_updated": "Fri, 18 Oct 2019 17:01:00 +0000",
      "direction": "outbound-api",
      "duration": "4",
      "end_time": "Fri, 18 Oct 2019 17:03:00 +0000",
      "forwarded_from": "calledvia1",
      "from": "+13051416799",
      "from_formatted": "(305) 141-6799",
      "phone_number_sid": "PNdeadbeefdeadbeefdeadbeefdeadbeef",
      "price": "-0.200",
      "price_unit": "USD",
      "start_time": "Fri, 18 Oct 2019 17:02:00 +0000",
      "status": "completed",
      "subresource_uris": {
        "notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
        "recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
        "payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",
        "events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",
        "siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",
        "streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",
        "transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",
        "user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",
        "user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"
      },
      "to": "+13051913581",
      "to_formatted": "(305) 191-3581",
      "trunk_sid": "TKdeadbeefdeadbeefdeadbeefdeadbeef",
      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
      "queue_time": "1000"
    },
]
```

**Troubleshooting**

* `400 Bad Request`: If the `projectId` is missing in the request.
* `404 Not Found`: If the call list for the provided `projectId` is empty.
* `500 Internal Server Error`: For errors in fetching the call list.