List Identity Usage

GET /api/v1/forward/usage/identities This endpoint is for tenant-level usage queries and only supports Qoder PAT authentication. Identity AccessTokens target a single identity and are not allowed to access tenant-level usage data.

Headers

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

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	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	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/api/v1/forward/usage/identities?start_time=1783267200000&end_time=1784476800000&identity_id=idn_123' \
  -H "Authorization: Bearer $QODER_PAT"

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	Sum of CAS turn `duration_ms` converted to seconds.
`data[].credits`	number\|null	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	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`	PAT is invalid or expired, or an Identity AccessToken was used to access a tenant-level usage endpoint.
500	`api_error`	Forward session query or CAS session metrics query failed.

Notes

The time window uses a half-open interval: created_at >= start_time and created_at < end_time.
When CAS credit query is unavailable, the endpoint still returns session and duration stats with credits set to null.
session_ids is deduplicated and returned in lexicographic order.

First steps

Define your agent

Configure agent environment

Delegate work to your agent

Manage agent context

Best Practices

API reference

List Identity Usage

Headers

Query parameters

Example request

Example response

Response fields

Error codes

Notes

List Template Usage

List Sessions

​Headers

​Query parameters

​Example request

​Example response

​Response fields

​Error codes

​Notes

​Related

List Template Usage

List Sessions

Headers

Query parameters

Example request

Example response

Response fields

Error codes

Notes

Related