# Reports API

Traffic summaries by period, and the detail records for IoT (MQTT) messages.

## List IoT (MQTT) message records

`POST https://apiv2.telecomsxchange.com/buyers/iothistory`

Reference: https://help.telecomsxchange.com/reference/reports/#list-iot-mqtt-message-records

Lists the MQTT messages published or received by your IoT accounts between two times, newest first: account, topic, payload, direction, whether the message was authorised, and the amount charged. Free.

> Results can't be filtered by topic: filter on `topic` in your own code after fetching.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `date_from` | string | body | no | Start of the period, as YYYY-MM-DD HH:MM:SS. Defaults to 24 hours ago. Example `2026-10-01 00:00:00`. |
| `date_to` | string | body | no | End of the period, as YYYY-MM-DD HH:MM:SS. Defaults to now. Example `2026-10-22 00:00:00`. |
| `show` | string | body | no | good returns only authorised messages, bad only rejected ones. Leave empty for both. One of `good`, `bad`. |
| `pager` | integer | body | no | Maximum number of records to return. Default `50`. |
| `off` | integer | body | no | Number of records to skip, for paging. Default `0`. |
| `download` | integer | body | no | 1 returns all matching records as a CSV file (mqtt_messages.csv) instead of JSON. One of `0`, `1`. Default `0`. |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/iothistory" \
  -d date_from='2026-10-01 00:00:00' \
  -d date_to='2026-10-22 00:00:00'
```

### Response: Example

```json
{
  "status": "success",
  "mqtt_messages": [
    {
      "i_mqtt_message": "192",
      "i_account": "2203",
      "i_customer": "1014",
      "topic": "sensors/warehouse-3/temperature",
      "payload": "21.4",
      "direction": "1",
      "authorized": "1",
      "charged_amount": "0.0001",
      "ts": "2026-10-21 16:11:05",
      "account_name": "mqtt-warehouse"
    }
  ]
}
```

## Voice summary report

`POST https://apiv2.telecomsxchange.com/buyers/voice/summary`

Reference: https://help.telecomsxchange.com/reference/reports/#voice-summary-report

Totals your voice traffic per day or per month: spend, billed minutes and number of calls, optionally narrowed to some of your accounts, purchased routes and destinations. Returns JSON, or a CSV file when `download=1`. Free.

> A destination that matches nothing returns zero totals rather than an error. Write destinations without spaces around the first hyphen: EGYPT-Mobile - Vodafone, not EGYPT - Mobile - Vodafone.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `date_from` | string | body | no | Start of the range, inclusive, as YYYY-MM-DD HH:MM:SS. Send both dates, or neither for the last 12 days. Example `2026-08-01 00:00:00`. |
| `date_to` | string | body | no | End of the range, inclusive, as YYYY-MM-DD HH:MM:SS. Use 23:59:59 to include the whole final day. Example `2026-10-31 23:59:59`. |
| `time_format` | string | body | no | daily returns one row per day; any other value, such as monthly, returns one row per calendar month. Default `daily`. Example `monthly`. |
| `status` | string | body | no | good counts answered calls, bad counts failed calls, any other value (such as all) counts both. With all, spend and minutes come from answered calls and the call count includes failed calls. Default `good`. Example `all`. |
| `accounts[]` | integer | body | no | One of your voice account IDs; repeat the field for several. Omit to include all your voice accounts. Example `1022`. |
| `connections[]` | integer | body | no | `i_connection` of a purchased voice route; repeat the field for several. Omit to include all your purchased voice routes. Example `653`. |
| `destination_descriptions[]` | string | body | no | A destination as the country and the description joined by a single hyphen with no spaces around it, for example EGYPT-Mobile - Vodafone; repeat for several. % works as a wildcard, so EGYPT-% covers the whole country. Omit for all destinations. Example `EGYPT-Mobile - Vodafone`. |
| `download` | integer | body | no | 1 returns a CSV attachment (voice_summary.csv) instead of JSON. One of `0`, `1`. Default `0`. Example `0`. |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/voice/summary" \
  -d date_from='2026-08-01 00:00:00' \
  -d date_to='2026-10-31 23:59:59' \
  -d time_format=monthly \
  -d status=all \
  -d accounts[]=1022 \
  -d connections[]=653 \
  -d destination_descriptions[]='EGYPT-Mobile - Vodafone' \
  -d download=0
```

### Response: Example

```json
{
  "status": "success",
  "summary": [
    {
      "date_from": "2026-08-01 00:00:00",
      "date_to": "2026-08-31 23:59:59",
      "date_text": "2026 Aug",
      "total_amt": 67.245,
      "total_minutes": 619.3167,
      "total_calls": 1034
    },
    {
      "date_from": "2026-09-01 00:00:00",
      "date_to": "2026-09-30 23:59:59",
      "date_text": "2026 Sep",
      "total_amt": 327.73,
      "total_minutes": 2982.7667,
      "total_calls": 5299
    },
    {
      "date_from": "2026-10-01 00:00:00",
      "date_to": "2026-10-31 23:59:59",
      "date_text": "2026 Oct",
      "total_amt": 0,
      "total_minutes": 0,
      "total_calls": 0
    }
  ]
}
```

## SMS summary report

`POST https://apiv2.telecomsxchange.com/buyers/sms/summary`

Reference: https://help.telecomsxchange.com/reference/reports/#sms-summary-report

Totals your SMS traffic per day or per month: spend and number of messages, optionally narrowed to some of your SMS accounts, purchased SMS routes and destinations. Returns JSON, or a CSV file broken down by sender ID when `download=1`. Free.

> A destination that matches nothing returns zero totals rather than an error. To cover a whole country, send the country followed by -%, for example OMAN-%.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `date_from` | string | body | no | Start of the range, inclusive, as YYYY-MM-DD HH:MM:SS. Send both dates, or neither for the last 12 days. Example `2026-08-01 00:00:00`. |
| `date_to` | string | body | no | End of the range, inclusive, as YYYY-MM-DD HH:MM:SS. Use 23:59:59 to include the whole final day. Example `2026-09-30 23:59:59`. |
| `time_format` | string | body | no | daily returns one row per day; any other value, such as monthly, returns one row per calendar month. Default `daily`. Example `monthly`. |
| `status` | string | body | no | good counts messages accepted by the route, bad counts messages that failed, any other value (such as all) counts both. Default `good`. Example `all`. |
| `accounts[]` | integer | body | no | One of your SMPP or IoT account IDs; repeat the field for several. Omit to include all of them. Example `1855`. |
| `connections[]` | integer | body | no | `i_connection` of a purchased SMS route; repeat the field for several. Omit to include all your purchased SMS routes. Example `1160`. |
| `destination_descriptions[]` | string | body | no | A destination as the country and the description joined by a single hyphen with no spaces around it, for example OMAN-Mobile - Omantel; repeat for several. % works as a wildcard, so OMAN-% covers the whole country. Omit for all destinations. Example `OMAN-%`. |
| `download` | integer | body | no | 1 returns a CSV attachment (sms_summary.csv) with one row per period and sender ID instead of JSON. One of `0`, `1`. Default `0`. Example `0`. |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/sms/summary" \
  -d date_from='2026-08-01 00:00:00' \
  -d date_to='2026-09-30 23:59:59' \
  -d time_format=monthly \
  -d status=all \
  -d accounts[]=1855 \
  -d connections[]=1160 \
  -d destination_descriptions[]='OMAN-%' \
  -d download=0
```

### Response: Example

```json
{
  "status": "success",
  "summary": [
    {
      "date_from": "2026-08-01 00:00:00",
      "date_to": "2026-08-31 23:59:59",
      "date_text": "2026 Aug",
      "total_amt": 3.3606,
      "total_sms": 28
    },
    {
      "date_from": "2026-09-01 00:00:00",
      "date_to": "2026-09-30 23:59:59",
      "date_text": "2026 Sep",
      "total_amt": 1.8883,
      "total_sms": 85
    }
  ]
}
```