# Project usage summary

**Documentation:** /reference/api-reference/projects/postProjectUsageSummary

Aggregated metering usage for the authenticated project only. Values are summed from raw metering events grouped by `entity_type`.

---

## POST `/api/v3.1/project/usage/summary`

**Endpoint:** `https://backend.composio.dev/api/v3.1/project/usage/summary`

**Summary:** Project usage summary

Aggregated metering usage for the authenticated project only. Values are summed from raw metering events grouped by `entity_type`.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Request Body

**Schema:**

- `from` (number): Inclusive range start (Unix epoch milliseconds). Defaults to 30 days before `to`.
- `to` (number): Exclusive range end (Unix epoch milliseconds). Defaults to now.
- `entity_types` (array<string>): Filter to these metering entity types. Omit for all types.
- `filters` (object)
  - `user_id` (array,null): Filter to events matching these external end-user IDs. OR logic within the array.
  - `session_id` (array,null): Filter to events matching these session IDs. OR logic within the array.

**Example:**

```json
{
  "from": 1,
  "to": 1,
  "entity_types": [
    "string"
  ],
  "filters": {
    "user_id": null,
    "session_id": null
  }
}
```

### Responses

#### 200 - Usage aggregates for the project.

**Response Schema:**

- `entities` (object) *(required)*
  - `[key: string]` (object)
    - `unit` (string) *(required)*
    - `total_quantity` (string) *(required)*
    - `event_count` (integer) *(required)*

**Example Response:**

```json
{
  "entities": {
    "key": {
      "unit": "string",
      "total_quantity": "string",
      "event_count": 0
    }
  }
}
```

#### 400 - Invalid time range, entity_types, or query parameters.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Authentication required.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 403 - Forbidden.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Project not found.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Failed to load usage from analytics store or feature configuration.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X POST "https://backend.composio.dev/api/v3.1/project/usage/summary" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": 1,
    "to": 1,
    "entity_types": [
      "string"
    ],
    "filters": {
      "user_id": null,
      "session_id": null
    }
  }'
```