Get Daily Usage by User

Description

Retrieve daily TURN bandwidth totals for every credential username in the selected date range. The response keeps username-level granularity and includes the label attached to each credential when available.

GET

https://<appname>.metered.live/api/v2/turn/usage_daily_by_user?secretKey=<YOUR_SECRET_KEY>

<appname> - replace it with the name of your app.

Request

GET /api/v2/turn/usage_daily_by_user

Query Parameters

Parameter	Description	Data Type
secretKey	Required. The account secret key used for server-side authentication.	String
startDate	Optional. Inclusive start date in YYYY-MM-DD (UTC). Defaults to 6 days before endDate. Earliest allowed date is 3 months back.	String
endDate	Optional. Inclusive end date in YYYY-MM-DD (UTC). Defaults to today. Future dates are clamped to the current day.	String
page	Optional. 1-based page number. Each page returns 7 consecutive days. Defaults to 1.	Number

Rate limit: 4 requests per minute per app.

Responses

Success Response

HTTP Status: 200 OK

Body:

{
  "data": [
    {
      "date": "2024-05-14",
      "usage": [
        {
          "username": "user-123",
          "label": "marketing-team",
          "usageInGB": 2.47
        },
        {
          "username": "user-789",
          "label": "unlabeled",
          "usageInGB": 0.63
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "days_per_page": 7,
    "has_more": true,
    "total_days": 14,
    "total_pages": 2
  },
  "period": {
    "start": "2024-05-08",
    "end": "2024-05-21",
    "page_start": "2024-05-14",
    "page_end": "2024-05-20"
  }
}

Field	Description	Data Type
data[].date	UTC date for the usage entry.	String
data[].usage[]	Usage records sorted by descending usageInGB for that day.	Array
data[].usage[].username	TURN credential username.	String
data[].usage[].label	Label assigned to the credential, or "unlabeled" when none exists.	String
data[].usage[].usageInGB	Total relay bandwidth for the username on that day (rounded to 2 decimals).	Number
pagination	Paging metadata. days_per_page is fixed at 7. has_more is false when you have reached the final page.	Object
period	Overall reporting window plus the page-specific range. page_start and page_end are null when no data exists for the requested page.	Object

Dates are aggregated and returned in UTC. Requesting a page beyond the available range responds with an empty data array and has_more: false.

Error Responses

HTTP Status	Message	When it Happens
400 Bad Request	{"message":"invalid secretKey"}	Secret key is missing or does not match any app.
400 Bad Request	{"message":"Invalid request. Not subscribed to any turn server plan"}	The app is not subscribed to a TURN Server plan.
400 Bad Request	{"message":"api not available under free plan"}	The app uses the free plan; upgrade to access this endpoint.
400 Bad Request	{"message":"Invalid startDate format. Use ISO 8601 format (YYYY-MM-DD)"}	Provided startDate is not ISO 8601.
400 Bad Request	{"message":"Invalid endDate format. Use ISO 8601 format (YYYY-MM-DD)"}	Provided endDate is not ISO 8601.
400 Bad Request	{"message":"Start date cannot be more than 3 months in the past"}	The requested window starts earlier than 3 months ago.
400 Bad Request	{"message":"Date range cannot exceed 3 months (92 days)"}	startDate and endDate span more than 92 days.
400 Bad Request	{"message":"Start date must be before or equal to end date"}	startDate is after endDate.
500 Internal Server Error	{"message":"Internal error occurred, contact support and provide the event id: <EVENT_ID>"}	An unexpected error occurred. Provide the event id to support.

Notes

• Works only for TURN Server premium plans.
• Labels are pulled from your TURN credentials; credentials without a label appear as "unlabeled".
• A page value less than 1 defaults to the first page.