get--v3-sms-history
Retrieve and filter SMS history by status, recipient, sender, subaccount, or date range. Sort and paginate records to review message activity and resolve delivery issues.
Instructions
View SMS History
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Allows filtering of results based on your search criteria. The query should be in the format `field_name:value`. 1. **Field Name**: The field within the SMS history you want to filter by. You can use the following fields: - _Status_: The status of the SMS. Available values for status are: Queued, Completed, Scheduled, WaitApproval, Failed, Cancelled, CancelledAfterReview, Received, Sent. - _To_: The recipient of the SMS. - _from_: The sender of the SMS. - _subaccount_id_: The sub-account identifier. - _message_id_: The ID of your SMS. 2. **Value**: The text or keyword you're searching for within the specified field. If left empty after the colon, the filter will look for all templates with any value in the **Field Name**. For example, if you are searching for a SMS with the status of Scheduled, the final query would look like this: `q=status:Scheduled` <div class="info-box"> <h4><i class="fas fa-info-circle"></i> Note:</h4> <div> <p>Some characters have to be encoded. For example, if you are searching for SMS sent from the phone number +61437085284, your search query q would be:<br/></p> <ul> <li>q=from:%2B61437085284</li> </ul> <p>You can use the <a href="https://www.urlencoder.org/" target="_blank">URL encoder</a> to encode the text. If a character is not an alphanumeric character (A-Z, a-z, 0-9), it is typically either reserved or unsafe and should be encoded.</p> </div> </div> | |
| page | No | The page number to retrieve. Use this parameter to navigate through the [pagination](/#pagination) results. The default value is 1. | |
| limit | No | The number of items to return per page. This parameter controls the size of each page of results. The default value is 15. | |
| date_to | No | End date to filter results. It should be in <a href="http://help.clicksend.com/what-is-a-unix-timestamp" target="_blank">Unix format</a>. | |
| order_by | No | Specifies the field and order to sort the results by. The value is composed of the field name followed by a colon and the sort direction (_asc_ for ascending or _desc_ for descending). The default sort order is by _date_ in ascending order. You can use the following fields: - _date_ - _username_ - _from_ - _to_ - _status_ - _body_ For example, if you want to order by the most recently sent SMS, you should sort by date in descending order. The query would look like this: `order_by=date:desc` | |
| date_from | No | Start date to filter results. It should be in <a href="http://help.clicksend.com/what-is-a-unix-timestamp" target="_blank">Unix format</a>. | |
| user_date_request | No | [FOR AI AGENTS] When user requests dates in natural language (e.g., 'Aug 5 2025', 'yesterday', 'last Tuesday'), pass the EXACT original user message here. The backend will parse this to generate correct Unix timestamps for date_from/date_to, avoiding common AI errors like wrong years. This parameter overrides any date_from/date_to values if provided. |