Rayobyte

➡️ Overview

The Rayobyte Usage Statistics API provides programmatic access to daily bandwidth usage for supported proxy products.

You can use the API to:

• Monitor bandwidth consumption
• Export usage data into reporting systems or spreadsheets
• Build internal dashboards
• Create automated usage checks or alerts
• Review daily usage trends across a billing period

Important: Usage statistics are product-specific. Select the endpoint that matches the product you want to report on.

➡️ Supported Products

To access the API, sign in to your Rayobyte Dashboard, open the relevant product, select Statistics, and then open the API tab.

The base URL for all endpoints is:

https://app.rayobyte.com

➡️ What the API Is For

The bandwidth endpoints return a daily time series for the selected product and date range.

Common use cases include:

• Monitoring bandwidth consumption
• Feeding usage data into internal dashboards or spreadsheets
• Creating usage alerts or scheduled reports
• Reviewing daily trends across a billing period
• Reconciling product-level statistics with your own operational records

Each request reports usage for one product. If you need to combine multiple products into one report, call each product endpoint separately and combine the results in your application.

➡️ Authentication

The Usage Statistics API uses a Bearer Token generated from the product's Statistics → API tab.

Send the token in the HTTP Authorization header:

Authorization: Bearer <YOUR_API_TOKEN>

API tokens begin with rbapi_. Because the token can access usage statistics for your account, treat it like a password.

• Store it securely in a secrets manager or environment variable.
• Do not place it in source control, support tickets, screenshots, client-side code, or public documentation.
• Avoid printing the token in application or CI logs.
• Use HTTPS only.
• Rotate the token immediately if it becomes exposed.

You can use the Rotate option in the dashboard to invalidate the existing token and generate a new one.

➡️ Request Format

• Method: GET
• Request Body: None
• Authentication: Bearer Token
• Response Format: JSON

Query Parameters

The requested date range can cover no more than 366 days per request.

➡️ Endpoint Template

GET https://app.rayobyte.com/api/users/stats/{product}/bandwidth?from={YYYY-MM-DD}&to={YYYY-MM-DD}&unit=Gb

Supported {product} values are:

• residential
• web-unblocker
• rotating-isp
• rotating-dc

➡️ Quick Start with cURL

The following example requests Residential bandwidth usage for July 14 through August 13, 2026:

curl --fail-with-body \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  "https://app.rayobyte.com/api/users/stats/residential/bandwidth?from=2026-07-14&to=2026-08-13&unit=Gb"

To query another product, replace residential with:

• web-unblocker
• rotating-isp
• rotating-dc

For safer local use, store the token in an environment variable:

export RAYOBYTE_API_TOKEN="<YOUR_API_TOKEN>"

curl --fail-with-body \
  -H "Authorization: Bearer ${RAYOBYTE_API_TOKEN}" \
  "https://app.rayobyte.com/api/users/stats/rotating-isp/bandwidth?from=2026-07-14&to=2026-08-13&unit=Gb"

➡️ JavaScript Example

const product = "web-unblocker";

const params = new URLSearchParams({
  from: "2026-07-14",
  to: "2026-08-13",
  unit: "Gb",
});

const response = await fetch(
  `https://app.rayobyte.com/api/users/stats/${product}/bandwidth?${params}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.RAYOBYTE_API_TOKEN}`,
      Accept: "application/json",
    },
  },
);

if (!response.ok) {
  throw new Error(`Rayobyte API returned HTTP ${response.status}`);
}

const result = await response.json();
console.log(result.data.as_of, result.data.series);

➡️ Python Example

import os
import requests

product = "rotating-dc"
url = f"https://app.rayobyte.com/api/users/stats/{product}/bandwidth"

response = requests.get(
    url,
    headers={
        "Authorization": f"Bearer {os.environ['RAYOBYTE_API_TOKEN']}",
        "Accept": "application/json",
    },
    params={
        "from": "2026-07-14",
        "to": "2026-08-13",
        "unit": "Gb",
    },
    timeout=60,
)

response.raise_for_status()

result = response.json()
print(result["data"]["as_of"])

for bucket in result["data"]["series"]:
    print(bucket["traffic_date"], bucket["total_value"])

➡️ Response Format

A successful response follows this structure:

{
  "status": "SUCCESS",
  "date": "...",
  "data": {
    "product": "residential",
    "source": "aggregator_union",
    "unit": "Gb",
    "from": "2026-07-14",
    "to": "2026-08-13",
    "as_of": "2026-08-06T10:00:00Z",
    "series": [
      {
        "traffic_date": "2026-07-14",
        "total_value": 12.34
      }
    ]
  }
}

Response Fields

When storing or displaying results, use the returned data.product, data.unit, and data.as_of values rather than assuming fixed values.

➡️ Data Behavior and Current Limitations

• Every usage bucket represents a UTC day.
• The current day's usage is partial. Check data.as_of to determine how current the data is.
• Each request is limited to a maximum date range of 366 days.
• The current API version reports master-account traffic only. Sub-account usage is not currently included.
• Per-country statistics are currently available only for Residential Proxies.
• Per-country statistics are not available for Web Unblocker, Rotating ISP, or Rotating Datacenter.
• Dashboard views such as Usage, Per Country, and Domain List are separate features and should not be assumed to use the same API format.

➡️ Building a Request in the Dashboard

1. Sign in to app.rayobyte.com.
2. Select Residential, Web Unblocker, Rotating ISP, or Rotating DC.
3. Open Statistics and select the API tab.
4. Under Your API Token, copy the Bearer Token. Reveal it only when necessary.
5. Under Build a request, select Bandwidth (JSON).
6. Select Gb and choose your From and To dates.
7. Select Copy cURL to copy a ready-to-run command.
8. Run the command from a trusted terminal or adapt the request URL and Authorization header in your application.

Important: The dashboard may insert your real API token into the copied command even while the token appears masked on screen. Review where you paste, save, or share the command.

➡️ Troubleshooting

A Successful Response Contains No Usage

A successful request may return an empty series array if no usage was recorded for the selected product, master account, and date range.

"series": []

This is a successful zero-data result, not necessarily an API failure. Confirm the selected product and date range.

A Large Request Times Out

Large Residential usage queries may require more processing time than shorter queries.

If a large request times out, retry using smaller, non-overlapping UTC date ranges and combine the returned daily usage records in your application.

Authentication Fails

Verify that the Authorization header uses the following exact format, including the space after Bearer:

Authorization: Bearer <YOUR_API_TOKEN>

Also confirm that the token has not been rotated, truncated, or copied with extra whitespace.

If you believe the token may have been exposed, rotate it rather than continuing to use it.

The Date Range Is Rejected

Confirm that:

• Dates use the YYYY-MM-DD format.
• from is not later than to.
• The requested date range does not exceed 366 days.

Today's Usage Looks Lower Than Expected

The current day's usage bucket is incomplete until the UTC day has finished.

Check data.as_of before comparing today's usage with completed days.

Sub-Account Usage Is Missing

The current API version reports master-account traffic only. Sub-account traffic is not currently included.

Per-Country Data Is Unavailable

Per-country statistics are currently available only for Residential Proxies.

Web Unblocker, Rotating ISP, and Rotating Datacenter APIs provide product-level bandwidth statistics but not per-country statistics.

The API Returns a Non-Success HTTP Status

Do not process the response as successful usage data.

Record the HTTP status and response body without logging your Bearer Token.

• For client errors, verify your authentication and request parameters.
• For temporary server errors, retry using a limited exponential backoff strategy.

➡️ Best Practices

• Keep your API token outside application source code.
• Validate the product against the supported product identifiers.
• Generate dates in YYYY-MM-DD format using UTC.
• Keep each request within the 366-day maximum.
• Check the HTTP status before processing the response.
• Confirm that status is SUCCESS.
• Store product, unit, and as_of alongside usage data.
• Treat the current UTC day's statistics as partial.
• Do not expect sub-account or non-Residential per-country usage data.
• Rotate exposed API tokens immediately.

➡️ Need Help?

If you need assistance using the Usage Statistics API or troubleshooting a request, our support team is happy to help.

When contacting support, please include:

• The product you are querying
• The request URL, with your API token removed
• The HTTP status code
• The error message or response body, with sensitive information removed
• Email: support@rayobyte.com
• Submit a Ticket: https://rayobyte.com/contact-us/