# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.talkstack.ai/call/get-call-history.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.