List Identity Usage

GET /api/v1/forward/usage/identities Query Identity-level Usage summaries and session details for the current account within a specified time window.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`

Query parameters

Parameter	Type	Required	Default	Description
`start_time`	integer	Yes	-	Unix millisecond timestamp. Start of the time window (inclusive).
`end_time`	integer	Yes	-	Unix millisecond timestamp. End of the time window (exclusive). Must be greater than `start_time` and span no more than 31 days.
`identity_id`	string	No	-	Filter by a single Forward Identity ID.
`identity_ids`	string/string[]	No	-	Filter by multiple Forward Identity IDs. Supports comma-separated values or repeated query parameters.
`template_id`	string	No	-	Filter by a single Forward Template ID.
`template_ids`	string/string[]	No	-	Filter by multiple Forward Template IDs. Supports comma-separated values or repeated query parameters.

Example request

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/usage/identities?start_time=1783267200000&end_time=1784476800000&identity_id=idn_123' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Example response

HTTP 200 OK

{
  "type": "identity_usage.list",
  "start_time": 1783267200000,
  "end_time": 1784476800000,
  "data": [
    {
      "type": "identity_usage",
      "identity_id": "idn_123",
      "session_count": 5,
      "duration_seconds": 420,
      "credits": 1.23,
      "session_ids": ["sess_1", "sess_2"]
    }
  ]
}

Response fields

Field	Type	Description
`type`	string	Always `identity_usage.list`.
`start_time`	integer	Requested time window start.
`end_time`	integer	Requested time window end.
`data`	array	Usage list grouped by Identity.
`data[].type`	string	Always `identity_usage`.
`data[].identity_id`	string	Forward Identity ID.
`data[].session_count`	integer	Number of Forward sessions.
`data[].duration_seconds`	integer	Forward session runtime aggregated and converted to seconds.
`data[].credits`	number	Credit consumption aggregated by session, rounded to two decimal places. `null` when Credit query is unavailable.
`data[].session_ids`	string[]	Forward session ID list for this Identity.

Error codes

HTTP	Type	Code	Trigger
400	`invalid_request_error`	-	Missing `start_time`/`end_time`, invalid time format, `end_time <= start_time`, or time span exceeds 31 days.
401	`authentication_error`	`authentication_required`	The PAT is invalid or expired.
500	`api_error`	-	The Forward session query or usage metrics query failed.

List Identity Usage

Headers

Query parameters

Example request

Example response

Response fields

Error codes

List Template Usage

List Sessions

​Headers

​Query parameters

​Example request

​Example response

​Response fields

​Error codes

​Related

List Template Usage

List Sessions

Headers

Query parameters

Example request

Example response

Response fields

Error codes

Related