> ## 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 Identity Usage

> Query session count, duration, credit consumption, and session details by Forward Identity.

`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

```bash theme={null}
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**

```json theme={null}
{
  "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.

## Related

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

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