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

# Usage

> Organisation usage metrics (mgmt.usage).

### UsageResource

```python
class UsageResource(http: HttpClient, config: ModusConfig)
```

Bases: `object`

Query organisation usage metrics.

#### list()

```python
list(*, since: str, until: str, rollup: Literal['hour', 'day'], model: str | None = None, user_email: Sequence[str] | None = None) → ListUsageResponseDto
```

List usage metrics for your organisation over a time window.

* Parameters:

  * **since** – Start of the window (ISO 8601, inclusive).

  * **until** – End of the window (ISO 8601, exclusive).

  * **rollup** – Bucket size for each row (`hour` or `day`).

  * **model** – Optional filter to a single model name.

  * **user\_email** – Optional filter to one or more acting-user emails.

* Raises:

  * [**UnprocessableError**](<> "modus._exceptions.UnprocessableError") – The request was rejected by the API.

  * [**AuthenticationError**](<> "modus._exceptions.AuthenticationError") – Invalid or missing API key.

#### list\_users()

```python
list_users(*, since: str, until: str) → ListUsageUsersResponseDto
```

List distinct acting-user emails observed in a time window.

* Parameters:

  * **since** – Start of the window (ISO 8601, inclusive).

  * **until** – End of the window (ISO 8601, exclusive).

* Raises:

  * [**UnprocessableError**](<> "modus._exceptions.UnprocessableError") – The request was rejected by the API.

  * [**AuthenticationError**](<> "modus._exceptions.AuthenticationError") – Invalid or missing API key.

### AsyncUsageResource

```python
class AsyncUsageResource(http: AsyncHttpClient, config: ModusConfig)
```

Bases: `object`

#### list()

```python
async list(*, since: str, until: str, rollup: Literal['hour', 'day'], model: str | None = None, user_email: Sequence[str] | None = None) → ListUsageResponseDto
```

List usage metrics for your organisation over a time window.

* Parameters:

  * **since** – Start of the window (ISO 8601, inclusive).

  * **until** – End of the window (ISO 8601, exclusive).

  * **rollup** – Bucket size for each row (`hour` or `day`).

  * **model** – Optional filter to a single model name.

  * **user\_email** – Optional filter to one or more acting-user emails.

* Raises:

  * [**UnprocessableError**](<> "modus._exceptions.UnprocessableError") – The request was rejected by the API.

  * [**AuthenticationError**](<> "modus._exceptions.AuthenticationError") – Invalid or missing API key.

#### list\_users()

```python
async list_users(*, since: str, until: str) → ListUsageUsersResponseDto
```

List distinct acting-user emails observed in a time window.

* Parameters:

  * **since** – Start of the window (ISO 8601, inclusive).

  * **until** – End of the window (ISO 8601, exclusive).

* Raises:

  * [**UnprocessableError**](<> "modus._exceptions.UnprocessableError") – The request was rejected by the API.

  * [**AuthenticationError**](<> "modus._exceptions.AuthenticationError") – Invalid or missing API key.