# Org usage breakdown

**Documentation:** /reference/api-reference/organization/postOrgUsageByEntityType

Grouped metering usage breakdown for the authenticated organization. Groups results by a single dimension or column key. By default includes all projects; use `filters.project_id` to restrict.

---

## POST `/api/v3.1/org/usage/{entity_type}`

**Endpoint:** `https://backend.composio.dev/api/v3.1/org/usage/{entity_type}`

**Summary:** Org usage breakdown

Grouped metering usage breakdown for the authenticated organization. Groups results by a single dimension or column key. By default includes all projects; use `filters.project_id` to restrict.

### Authentication

**OrgApiKeyAuth** - API Key in `header` header `x-org-api-key`

### Path Parameters

- `entity_type` (string) *(required)*: Metering entity type to break down (e.g. `tool_calls`, `sessions`).

### 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.
- `group_by` (string): Dimension or column to group results by. Defaults to `tool_slug` for tool_calls and `user_id` for sessions.
- `order_by` (enum: "key" | "total_quantity" | "event_count"): Field to order groups by. Defaults to `total_quantity`.
- `order_direction` (enum: "asc" | "desc"): Sort direction. Defaults to `desc`.
- `limit` (integer): Maximum number of groups to return. Defaults to 100, max 1000.
- `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.
  - `project_id` (array,null): Restrict aggregates to one or more projects (must belong to the authenticated organization). OR logic within the array. Omit for org-wide totals.

**Example:**

```json
{
  "from": 1,
  "to": 1,
  "group_by": "string",
  "order_by": "key",
  "order_direction": "asc",
  "limit": 1,
  "filters": {
    "user_id": null,
    "session_id": null,
    "project_id": null
  }
}
```

### Responses

#### 200 - Usage breakdown for the organization.

**Response Schema:**

- `entity_type` (string) *(required)*
- `unit` (string) *(required)*
- `total_quantity` (string) *(required)*
- `event_count` (integer) *(required)*
- `groups` (array<object>) *(required)*
  - Array items:
    - `key` (string) *(required)*
    - `total_quantity` (string) *(required)*
    - `event_count` (integer) *(required)*

**Example Response:**

```json
{
  "entity_type": "string",
  "unit": "string",
  "total_quantity": "string",
  "event_count": 0,
  "groups": [
    {
      "key": "string",
      "total_quantity": "string",
      "event_count": 0
    }
  ]
}
```

#### 400 - Invalid entity_type, group_by, time range, 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 - Unknown project_id or project not in this organization.

**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/org/usage/string" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": 1,
    "to": 1,
    "group_by": "string",
    "order_by": "key",
    "order_direction": "asc",
    "limit": 1,
    "filters": {
      "user_id": null,
      "session_id": null,
      "project_id": null
    }
  }'
```