> For the complete documentation index, see [llms.txt](https://docs.iproyal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iproyal.com/proxies/residential/api/reports.md).
# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.iproyal.com/proxies/residential/api/reports.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.