> This page is for Developers.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.smartsim.telecom.li/llms.txt.

# SIM usage and cost statistics

GET https://smartsim.telecom.li/api/v1/sim/{sim_id}/stats

You can only retrieve data traffic costs for organizations without multi-inclusive volumes.

Retrieves SIM usage and cost statistics for a given ID.
Usage statistics are sorted by `data` and `sms`.

Returns statistics from the following periods:

* `last_month`: Previous billing month, from the first to last day (for example, February 1-29, 2024, when you send the request in March 2024).
* `current_month`: Current month, with statistics calculated up to and including the date requested (for example, March 1-8, 2024, when you sent the request on March 8, 2024).
* `last_hour`: Previous 60 minutes, accumulated per minute and organized by data or SMS received by the device (`rx`) and transmitted by the device (`tx`).

`last_month` and `current_month` are only included in the responses if traffic exists.
Those responses include a generated `id` value that's comprised of the SIM ID, year, month, and traffic type ID (`5` for data and `6` for SMS).

For example, if you send a request in March 2024 for SIM ID `123456`, the `id` for data in the current month is `1234562024035`.

Reference: https://docs.smartsim.telecom.li/developers/api/sim/sim-stats-by-id-get

## Authentication

- `Authorization` header (bearer token, required) — An `auth_token` should be provided to authenticate a session. To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).

## Request

### Path parameters

- `sim_id` (integer, required) — Numeric ID of a SIM

## Response

### 200

Successfully returned the SIM statistics associated with the provided `id`.

- `last_hour` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHour, required)
- `last_month` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonth, optional)
- `current_month` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonth, optional)

## Errors

### 403 Forbidden Error

Your role doesn't include the permission this endpoint requires. Most endpoints return `error_code`, `error_token`, and `message`. Some return only `status_code` and `message`.

- `error_code` (integer, optional)
- `error_token` (string, optional)
- `status_code` (integer, optional)
- `message` (string, optional)

## Types

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHour

- `data` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourData, optional)
- `sms` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourSms, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonth

- `data` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthData, optional)
- `sms` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthSms, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonth

- `data` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthData, optional)
- `sms` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthSms, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourData

- `rx` (list of list of ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourDataRxItemsItems, optional) — Data received by the device. Array index `0`: time as `HH:mm` string, index `1`: consumed volume
- `tx` (list of list of ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourDataTxItemsItems, optional) — Data transmitted by the device. Array index `0`: time as `HH:mm` string, index `1`: consumed volume

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourSms

- `rx` (list of list of ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourSmsRxItemsItems, optional) — SMS received by the device. Array index `0`: time as `HH:mm` string, index `1`: consumed volume
- `tx` (list of list of ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourSmsTxItemsItems, optional) — SMS transmitted by the device. Array index `0`: time as `HH:mm` string, index `1`: consumed volume

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthData

- `sim_id` (string, optional)
- `month` (string, optional)
- `volume` (string, optional)
- `volume_tx` (string, optional)
- `volume_rx` (string, optional)
- `traffic_type_id` (string, optional)
- `last_updated` (string, optional)
- `cost` (string, optional)
- `currency_id` (string, optional)
- `id` (double, optional)
- `traffic_type` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthDataTrafficType, optional)
- `currency` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthDataCurrency, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthSms

- `sim_id` (string, optional)
- `month` (string, optional)
- `volume` (string, optional)
- `volume_tx` (string, optional)
- `volume_rx` (string, optional)
- `traffic_type_id` (string, optional)
- `last_updated` (string, optional)
- `cost` (string, optional)
- `currency_id` (string, optional)
- `id` (double, optional)
- `traffic_type` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthSmsTrafficType, optional)
- `currency` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthSmsCurrency, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthData

- `sim_id` (string, optional)
- `month` (string, optional)
- `volume` (string, optional)
- `volume_tx` (string, optional)
- `volume_rx` (string, optional)
- `traffic_type_id` (string, optional)
- `last_updated` (string, optional)
- `cost` (string, optional)
- `currency_id` (string, optional)
- `id` (double, optional)
- `traffic_type` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthDataTrafficType, optional)
- `currency` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthDataCurrency, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthSms

- `sim_id` (string, optional)
- `month` (string, optional)
- `volume` (string, optional)
- `volume_tx` (string, optional)
- `volume_rx` (string, optional)
- `traffic_type_id` (string, optional)
- `last_updated` (string, optional)
- `cost` (string, optional)
- `currency_id` (string, optional)
- `id` (double, optional)
- `traffic_type` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthSmsTrafficType, optional)
- `currency` (ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthSmsCurrency, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourDataRxItemsItems

- string
- double

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourDataTxItemsItems

- string
- double

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourSmsRxItemsItems

- string
- double

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastHourSmsTxItemsItems

- string
- double

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthDataTrafficType

- `description` (string, optional)
- `unit` (string, optional)
- `id` (double, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthDataCurrency

- `code` (string, optional)
- `symbol` (string, optional)
- `id` (double, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthSmsTrafficType

- `description` (string, optional)
- `unit` (string, optional)
- `id` (double, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaLastMonthSmsCurrency

- `code` (string, optional)
- `symbol` (string, optional)
- `id` (double, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthDataTrafficType

- `description` (string, optional)
- `unit` (string, optional)
- `id` (double, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthDataCurrency

- `code` (string, optional)
- `symbol` (string, optional)
- `id` (double, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthSmsTrafficType

- `description` (string, optional)
- `unit` (string, optional)
- `id` (double, optional)

### ApiV1SimSimIdStatsGetResponsesContentApplicationJsonSchemaCurrentMonthSmsCurrency

- `code` (string, optional)
- `symbol` (string, optional)
- `id` (double, optional)

## Examples

**Response**

```json
{
  "last_hour": {
    "data": {
      "rx": [
        [
          "06:38",
          0
        ],
        [
          "06:39",
          0
        ],
        [
          "06:40",
          0
        ],
        [
          "06:41",
          0
        ],
        [
          "06:42",
          0
        ],
        [
          "06:43",
          0
        ],
        [
          "06:44",
          0
        ],
        [
          "06:45",
          0
        ],
        [
          "06:46",
          0
        ],
        [
          "06:47",
          0
        ],
        [
          "06:48",
          0
        ],
        [
          "06:49",
          0
        ],
        [
          "06:50",
          0
        ],
        [
          "06:51",
          0
        ],
        [
          "06:52",
          0
        ],
        [
          "06:53",
          0
        ],
        [
          "06:54",
          0
        ],
        [
          "06:55",
          0
        ],
        [
          "06:56",
          0
        ],
        [
          "06:57",
          0
        ],
        [
          "06:58",
          0
        ],
        [
          "06:59",
          0
        ],
        [
          "07:00",
          0
        ],
        [
          "07:01",
          0
        ],
        [
          "07:02",
          0
        ],
        [
          "07:03",
          0
        ],
        [
          "07:04",
          0
        ],
        [
          "07:05",
          0
        ],
        [
          "07:06",
          0
        ],
        [
          "07:07",
          0
        ],
        [
          "07:08",
          0
        ],
        [
          "07:09",
          0
        ],
        [
          "07:10",
          0
        ],
        [
          "07:11",
          0
        ],
        [
          "07:12",
          0
        ],
        [
          "07:13",
          0
        ],
        [
          "07:14",
          0
        ],
        [
          "07:15",
          0
        ],
        [
          "07:16",
          0
        ],
        [
          "07:17",
          0
        ],
        [
          "07:18",
          0
        ],
        [
          "07:19",
          0
        ],
        [
          "07:20",
          0
        ],
        [
          "07:21",
          0
        ],
        [
          "07:22",
          0
        ],
        [
          "07:23",
          0
        ],
        [
          "07:24",
          0
        ],
        [
          "07:25",
          0
        ],
        [
          "07:26",
          0
        ],
        [
          "07:27",
          0
        ],
        [
          "07:28",
          0
        ],
        [
          "07:29",
          0
        ],
        [
          "07:30",
          0
        ],
        [
          "07:31",
          0
        ],
        [
          "07:32",
          0
        ],
        [
          "07:33",
          0
        ],
        [
          "07:34",
          0
        ],
        [
          "07:35",
          0
        ],
        [
          "07:36",
          0
        ]
      ],
      "tx": [
        [
          "06:38",
          0
        ],
        [
          "06:39",
          0
        ],
        [
          "06:40",
          0
        ],
        [
          "06:41",
          0
        ],
        [
          "06:42",
          0
        ],
        [
          "06:43",
          0
        ],
        [
          "06:44",
          0
        ],
        [
          "06:45",
          0
        ],
        [
          "06:46",
          0
        ],
        [
          "06:47",
          0
        ],
        [
          "06:48",
          0
        ],
        [
          "06:49",
          0
        ],
        [
          "06:50",
          0
        ],
        [
          "06:51",
          0
        ],
        [
          "06:52",
          0
        ],
        [
          "06:53",
          0
        ],
        [
          "06:54",
          0
        ],
        [
          "06:55",
          0
        ],
        [
          "06:56",
          0
        ],
        [
          "06:57",
          0
        ],
        [
          "06:58",
          0
        ],
        [
          "06:59",
          0
        ],
        [
          "07:00",
          0
        ],
        [
          "07:01",
          0
        ],
        [
          "07:02",
          0
        ],
        [
          "07:03",
          0
        ],
        [
          "07:04",
          0
        ],
        [
          "07:05",
          0
        ],
        [
          "07:06",
          0
        ],
        [
          "07:07",
          0
        ],
        [
          "07:08",
          0
        ],
        [
          "07:09",
          0
        ],
        [
          "07:10",
          0
        ],
        [
          "07:11",
          0
        ],
        [
          "07:12",
          0
        ],
        [
          "07:13",
          0
        ],
        [
          "07:14",
          0
        ],
        [
          "07:15",
          0
        ],
        [
          "07:16",
          0
        ],
        [
          "07:17",
          0
        ],
        [
          "07:18",
          0
        ],
        [
          "07:19",
          0
        ],
        [
          "07:20",
          0
        ],
        [
          "07:21",
          0
        ],
        [
          "07:22",
          0
        ],
        [
          "07:23",
          0
        ],
        [
          "07:24",
          0
        ],
        [
          "07:25",
          0
        ],
        [
          "07:26",
          0
        ],
        [
          "07:27",
          0
        ],
        [
          "07:28",
          0
        ],
        [
          "07:29",
          0
        ],
        [
          "07:30",
          0
        ],
        [
          "07:31",
          0
        ],
        [
          "07:32",
          0
        ],
        [
          "07:33",
          0
        ],
        [
          "07:34",
          0
        ],
        [
          "07:35",
          0
        ],
        [
          "07:36",
          0
        ]
      ]
    },
    "sms": {
      "rx": [
        [
          "06:38",
          0
        ],
        [
          "06:39",
          0
        ],
        [
          "06:40",
          0
        ],
        [
          "06:41",
          0
        ],
        [
          "06:42",
          0
        ],
        [
          "06:43",
          0
        ],
        [
          "06:44",
          0
        ],
        [
          "06:45",
          0
        ],
        [
          "06:46",
          0
        ],
        [
          "06:47",
          0
        ],
        [
          "06:48",
          0
        ],
        [
          "06:49",
          0
        ],
        [
          "06:50",
          0
        ],
        [
          "06:51",
          0
        ],
        [
          "06:52",
          0
        ],
        [
          "06:53",
          0
        ],
        [
          "06:54",
          0
        ],
        [
          "06:55",
          0
        ],
        [
          "06:56",
          0
        ],
        [
          "06:57",
          0
        ],
        [
          "06:58",
          0
        ],
        [
          "06:59",
          0
        ],
        [
          "07:00",
          0
        ],
        [
          "07:01",
          0
        ],
        [
          "07:02",
          0
        ],
        [
          "07:03",
          0
        ],
        [
          "07:04",
          0
        ],
        [
          "07:05",
          0
        ],
        [
          "07:06",
          0
        ],
        [
          "07:07",
          0
        ],
        [
          "07:08",
          0
        ],
        [
          "07:09",
          0
        ],
        [
          "07:10",
          0
        ],
        [
          "07:11",
          0
        ],
        [
          "07:12",
          0
        ],
        [
          "07:13",
          0
        ],
        [
          "07:14",
          0
        ],
        [
          "07:15",
          0
        ],
        [
          "07:16",
          0
        ],
        [
          "07:17",
          0
        ],
        [
          "07:18",
          0
        ],
        [
          "07:19",
          0
        ],
        [
          "07:20",
          0
        ],
        [
          "07:21",
          0
        ],
        [
          "07:22",
          0
        ],
        [
          "07:23",
          0
        ],
        [
          "07:24",
          0
        ],
        [
          "07:25",
          0
        ],
        [
          "07:26",
          0
        ],
        [
          "07:27",
          0
        ],
        [
          "07:28",
          0
        ],
        [
          "07:29",
          0
        ],
        [
          "07:30",
          0
        ],
        [
          "07:31",
          0
        ],
        [
          "07:32",
          0
        ],
        [
          "07:33",
          0
        ],
        [
          "07:34",
          0
        ],
        [
          "07:35",
          0
        ],
        [
          "07:36",
          0
        ]
      ],
      "tx": [
        [
          "06:38",
          0
        ],
        [
          "06:39",
          0
        ],
        [
          "06:40",
          0
        ],
        [
          "06:41",
          0
        ],
        [
          "06:42",
          0
        ],
        [
          "06:43",
          0
        ],
        [
          "06:44",
          0
        ],
        [
          "06:45",
          0
        ],
        [
          "06:46",
          0
        ],
        [
          "06:47",
          0
        ],
        [
          "06:48",
          0
        ],
        [
          "06:49",
          0
        ],
        [
          "06:50",
          0
        ],
        [
          "06:51",
          0
        ],
        [
          "06:52",
          0
        ],
        [
          "06:53",
          0
        ],
        [
          "06:54",
          0
        ],
        [
          "06:55",
          0
        ],
        [
          "06:56",
          0
        ],
        [
          "06:57",
          0
        ],
        [
          "06:58",
          0
        ],
        [
          "06:59",
          0
        ],
        [
          "07:00",
          0
        ],
        [
          "07:01",
          0
        ],
        [
          "07:02",
          0
        ],
        [
          "07:03",
          0
        ],
        [
          "07:04",
          0
        ],
        [
          "07:05",
          0
        ],
        [
          "07:06",
          0
        ],
        [
          "07:07",
          0
        ],
        [
          "07:08",
          0
        ],
        [
          "07:09",
          0
        ],
        [
          "07:10",
          0
        ],
        [
          "07:11",
          0
        ],
        [
          "07:12",
          0
        ],
        [
          "07:13",
          0
        ],
        [
          "07:14",
          0
        ],
        [
          "07:15",
          0
        ],
        [
          "07:16",
          0
        ],
        [
          "07:17",
          0
        ],
        [
          "07:18",
          0
        ],
        [
          "07:19",
          0
        ],
        [
          "07:20",
          0
        ],
        [
          "07:21",
          0
        ],
        [
          "07:22",
          0
        ],
        [
          "07:23",
          0
        ],
        [
          "07:24",
          0
        ],
        [
          "07:25",
          0
        ],
        [
          "07:26",
          0
        ],
        [
          "07:27",
          0
        ],
        [
          "07:28",
          0
        ],
        [
          "07:29",
          0
        ],
        [
          "07:30",
          0
        ],
        [
          "07:31",
          0
        ],
        [
          "07:32",
          0
        ],
        [
          "07:33",
          0
        ],
        [
          "07:34",
          0
        ],
        [
          "07:35",
          0
        ],
        [
          "07:36",
          0
        ]
      ]
    }
  },
  "last_month": {
    "data": {
      "sim_id": "123456",
      "month": "2024-02-01",
      "volume": "29.166235",
      "volume_tx": "5.577229",
      "volume_rx": "23.589006",
      "traffic_type_id": "5",
      "last_updated": "2024-02-20T14:56:25.000Z",
      "cost": "6.10483935",
      "currency_id": "1",
      "id": 1234562024025,
      "traffic_type": {
        "description": "Data",
        "unit": "MB",
        "id": 5
      },
      "currency": {
        "code": "EUR",
        "symbol": "€",
        "id": 1
      }
    },
    "sms": {
      "sim_id": "123456",
      "month": "2024-02-01",
      "volume": "51.000000",
      "volume_tx": "36.000000",
      "volume_rx": "15.000000",
      "traffic_type_id": "6",
      "last_updated": "2024-02-26T10:52:42.000Z",
      "cost": "3.32",
      "currency_id": "1",
      "id": 1234562024026,
      "traffic_type": {
        "description": "SMS",
        "unit": "SMS",
        "id": 6
      },
      "currency": {
        "code": "EUR",
        "symbol": "€",
        "id": 1
      }
    }
  },
  "current_month": {
    "data": {
      "sim_id": "123456",
      "month": "2024-03-01",
      "volume": "0.848157",
      "volume_tx": "0.172846",
      "volume_rx": "0.675311",
      "traffic_type_id": "5",
      "last_updated": "2024-03-01T15:12:53.000Z",
      "cost": "0.21203925",
      "currency_id": "1",
      "id": 1234562024035,
      "traffic_type": {
        "description": "Data",
        "unit": "MB",
        "id": 5
      },
      "currency": {
        "code": "EUR",
        "symbol": "€",
        "id": 1
      }
    },
    "sms": {
      "sim_id": "123456",
      "month": "2024-03-01",
      "volume": "3.000000",
      "volume_tx": "2.000000",
      "volume_rx": "1.000000",
      "traffic_type_id": "6",
      "last_updated": "2024-03-01T14:20:42.000Z",
      "cost": "0.17",
      "currency_id": "1",
      "id": 1234562024036,
      "traffic_type": {
        "description": "SMS",
        "unit": "SMS",
        "id": 6
      },
      "currency": {
        "code": "EUR",
        "symbol": "€",
        "id": 1
      }
    }
  }
}
```

**SDK Code**

```python Retrieved
import requests

url = "https://smartsim.telecom.li/api/v1/sim/1/stats"

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

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Retrieved
const url = 'https://smartsim.telecom.li/api/v1/sim/1/stats';
const options = {method: 'GET', 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 Retrieved
package main

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

func main() {

	url := "https://smartsim.telecom.li/api/v1/sim/1/stats"

	req, _ := http.NewRequest("GET", 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 Retrieved
require 'uri'
require 'net/http'

url = URI("https://smartsim.telecom.li/api/v1/sim/1/stats")

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

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

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

```java Retrieved
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://smartsim.telecom.li/api/v1/sim/1/stats")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://smartsim.telecom.li/api/v1/sim/1/stats', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp Retrieved
using RestSharp;

var client = new RestClient("https://smartsim.telecom.li/api/v1/sim/1/stats");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Retrieved
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://smartsim.telecom.li/api/v1/sim/1/stats")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
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()
```