# Reports
## Get Data Usage Report
`GET` `/residential/data-usage-report`
Returns a data usage report as a CSV file for the given residential user or sub-user. The `hash` must belong to the authenticated caller's account. An empty date range returns a CSV with headers only.
**Query Parameters**
| Name | Type | Description |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| hash | String | The `app_hash` of the residential user or sub-user to generate the report for |
| date\_from | String | Start date of the report range in `Y-m-d` format |
| date\_to | String | End date of the report range in `Y-m-d` format. Must be on or after `date_from` |
| measurement\_unit | String | Unit for traffic values. One of: `B`, `KB`, `MB`, `GB` |
| rounding\_decimal | Integer | Number of decimal places for traffic values (must be `0` or greater) |
| time\_zone | String | *Optional.* IANA timezone name used to bucket traffic by date (e.g. `Europe/London`, `America/New_York`, `UTC`). Case-insensitive. When omitted, the default timezone is used |
All parameters except `time_zone` are required.
**Example request:**
{% tabs %}
{% tab title="cURL" %}
```bash
curl -X GET "https://resi-api.iproyal.com/v1/residential/data-usage-report?hash=asd48w4f5c1s2a5w4f8h5t6r1v&date_from=2026-01-01&date_to=2026-01-31&measurement_unit=GB&rounding_decimal=2" \
-H "Authorization: Bearer " \
-o data-usage-report.csv
```
{% endtab %}
{% tab title="PHP" %}
```php
'asd48w4f5c1s2a5w4f8h5t6r1v',
'date_from' => '2026-01-01',
'date_to' => '2026-01-31',
'measurement_unit' => 'GB',
'rounding_decimal' => 2,
]);
$ch = curl_init("https://resi-api.iproyal.com/v1/residential/data-usage-report?{$query}");
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ']);
curl_setopt($ch, CURLOPT_FILE, fopen('data-usage-report.csv', 'w'));
curl_exec($ch);
curl_close($ch);
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
params = {
"hash": "asd48w4f5c1s2a5w4f8h5t6r1v",
"date_from": "2026-01-01",
"date_to": "2026-01-31",
"measurement_unit": "GB",
"rounding_decimal": 2,
}
headers = {"Authorization": "Bearer "}
response = requests.get(
"https://resi-api.iproyal.com/v1/residential/data-usage-report",
params=params,
headers=headers,
stream=True,
)
with open("data-usage-report.csv", "wb") as f:
for chunk in response.iter_content(chunk_size=8192):
f.write(chunk)
```
{% endtab %}
{% tab title="Node.js" %}
```javascript
const fs = require("fs");
const https = require("https");
const params = new URLSearchParams({
hash: "asd48w4f5c1s2a5w4f8h5t6r1v",
date_from: "2026-01-01",
date_to: "2026-01-31",
measurement_unit: "GB",
rounding_decimal: "2",
});
const options = {
headers: { Authorization: "Bearer " },
};
https.get(
`https://resi-api.iproyal.com/v1/residential/data-usage-report?${params}`,
options,
(res) => res.pipe(fs.createWriteStream("data-usage-report.csv")),
);
```
{% endtab %}
{% tab title="Java" %}
```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://resi-api.iproyal.com/v1/residential/data-usage-report"
+ "?hash=asd48w4f5c1s2a5w4f8h5t6r1v"
+ "&date_from=2026-01-01"
+ "&date_to=2026-01-31"
+ "&measurement_unit=GB"
+ "&rounding_decimal=2"))
.header("Authorization", "Bearer ")
.GET()
.build();
client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of("data-usage-report.csv")));
```
{% endtab %}
{% tab title="Go" %}
```go
package main
import (
"io"
"net/http"
"os"
)
func main() {
url := "https://resi-api.iproyal.com/v1/residential/data-usage-report" +
"?hash=asd48w4f5c1s2a5w4f8h5t6r1v" +
"&date_from=2026-01-01&date_to=2026-01-31" +
"&measurement_unit=GB&rounding_decimal=2"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("Authorization", "Bearer ")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
out, _ := os.Create("data-usage-report.csv")
defer out.Close()
io.Copy(out, resp.Body)
}
```
{% endtab %}
{% tab title="C#" %}
```csharp
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer ");
var url = "https://resi-api.iproyal.com/v1/residential/data-usage-report"
+ "?hash=asd48w4f5c1s2a5w4f8h5t6r1v"
+ "&date_from=2026-01-01&date_to=2026-01-31"
+ "&measurement_unit=GB&rounding_decimal=2";
await using var stream = await client.GetStreamAsync(url);
await using var file = File.Create("data-usage-report.csv");
await stream.CopyToAsync(file);
```
{% endtab %}
{% endtabs %}
**Response**
The endpoint returns a CSV file as an attachment.
**Response headers:**
```
Content-Type: text/csv
Content-Disposition: attachment; filename="data-usage-{hash}-{date_from}-{date_to}.csv"
```
**Example response:**
```csv
date,hostname,port,data,measurement unit,requests count
2026-01-01,example.com,443,2.15,GB,1248
2026-01-01,api.example.com,443,4.78,GB,5310
2026-01-01,cdn.example.com,80,0.92,GB,612
2026-01-02,example.com,443,1.84,GB,1102
2026-01-02,api.example.com,443,5.23,GB,6047
2026-01-03,example.com,443,3.07,GB,2415
2026-01-03,images.example.com,443,8.41,GB,9823
,,total:,26.40,,26557
```
---
# 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.iproyal.com/proxies/residential/api/reports.md?ask=
```
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.