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:

cURL

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 <your_api_token>" \
    -o data-usage-report.csv

PHP

<?php
$query = http_build_query([
    'hash' => '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 <your_api_token>']);
curl_setopt($ch, CURLOPT_FILE, fopen('data-usage-report.csv', 'w'));
curl_exec($ch);
curl_close($ch);

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 <your_api_token>"}

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)

Node.js

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 <your_api_token>" },
};

https.get(
    `https://resi-api.iproyal.com/v1/residential/data-usage-report?${params}`,
    options,
    (res) => res.pipe(fs.createWriteStream("data-usage-report.csv")),
);

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 <your_api_token>")
    .GET()
    .build();

client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of("data-usage-report.csv")));

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 <your_api_token>")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    out, _ := os.Create("data-usage-report.csv")
    defer out.Close()
    io.Copy(out, resp.Body)
}

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer <your_api_token>");

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);

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:

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