# 报表
## 获取流量使用报表
`GET` `/residential/data-usage-report`
以CSV文件形式返回指定住宅代理用户或子用户的流量使用报表。`hash` 必须属于当前已认证账号。若日期范围为空，则返回仅包含表头的CSV文件。
**Query Parameters**
| 名称 | 类型 | 说明 |
| ----------------- | --- | -------------------------------------------------------------------------------------------- |
| hash | 字符串 | 要生成报表的住宅代理用户或子用户的 `app_hash` |
| date\_from | 字符串 | 报表范围的开始日期，格式为 `Y-m-d` |
| date\_to | 字符串 | 报表范围的结束日期，格式为 `Y-m-d`。必须等于或晚于 `date_from` |
| measurement\_unit | 字符串 | 流量数值的单位，可选值：`B`、`KB`、`MB`、`GB` |
| rounding\_decimal | 整数 | 流量数值的小数位数（必须为 `0` 或更大） |
| time\_zone | 字符串 | *可选。* 用于按日期归集流量的 IANA 时区名称（例如 `Europe/London`、`America/New_York`、`UTC`）。不区分大小写。若不提供，则使用默认时区。 |
除 `time_zone` 外，所有参数均为必填项。
**请求示例：**
{% 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 %}
**响应**
该接口以附件形式返回CSV文件。
**请求头：**
```
Content-Type: text/csv
Content-Disposition: attachment; filename="data-usage-{hash}-{date_from}-{date_to}.csv"
```
**响应示例：**
```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/cn/dai-li/huang-jia-zhu-zhai-dai-li/api/bao-biao.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.