> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Template Usage

> Query session count, active identity count, duration, and credit consumption by Forward Template.

`GET /api/v1/forward/usage/templates`

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. |
| `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.                           |
| `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.                           |

## Example request

```bash theme={null}
curl -s -X GET 'https://api.qoder.com/api/v1/forward/usage/templates?start_time=1783267200000&end_time=1784476800000&template_ids=tmpl_123,tmpl_456' \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "type": "template_usage.list",
  "start_time": 1783267200000,
  "end_time": 1784476800000,
  "data": [
    {
      "type": "template_usage",
      "template_id": "tmpl_123",
      "active_identities": 8,
      "session_count": 42,
      "duration_seconds": 3600,
      "credits": 12.34
    }
  ]
}
```

## 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      | 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. |

## 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 candidates come from Forward `ca_forward_sessions` and do not depend on a separate billing fact table.

## Related

<CardGroup cols={2}>
  <Card title="List Identity Usage" icon="chart-bar" href="/cloud-agents/api/forward/usage/list-identity-usage" />

  <Card title="List Sessions" icon="message" href="/cloud-agents/api/forward/sessions/list" />
</CardGroup>