GET /api/v1/forward/usage/templates
Query Template-level Usage summaries 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. |
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. |
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. |
Example request
Example response
HTTP 200 OK
Response fields
| Field | Type | Description |
|---|---|---|
type | string | Always template_usage.list. |
start_time | integer | Requested time window start. |
end_time | integer | Requested time window end. |
data | array | Usage list grouped by Template. |
data[].type | string | Always template_usage. |
data[].template_id | string | Forward Template ID. |
data[].active_identities | integer | Deduplicated count of Forward Identities under this Template. |
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. |
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. |