> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization

> Organization management

The Usage API returns **aggregated counts** of tool calls and sessions. Use it to power billing dashboards, customer-facing analytics, or internal utilization reports. For individual events, use the [Logs API](https://composio-preview.mintlify.site/reference/api-reference/logs).

There are two query shapes:

* **Summary**: totals across one or more entity types in a time window.
* **Breakdown**: one entity type, grouped by a dimension (tool, user, session, etc.).

Each shape comes in an org-scoped and a project-scoped flavor. The org-scoped endpoints are documented below; the project-scoped usage endpoints (`POST /api/v3.1/project/usage/*`) also appear on the [Projects](https://composio-preview.mintlify.site/reference/api-reference/projects) reference page.

## Authentication

| Endpoint | Header | Scope |
| - | - | - |
| `POST /api/v3.1/org/usage/summary` | `x-org-api-key` *(or org JWT)* | All projects in your org |
| `POST /api/v3.1/org/usage/{entity_type}` | `x-org-api-key` *(or org JWT)* | All projects in your org |
| `POST /api/v3.1/project/usage/summary` | `x-api-key` *(or cookie)* | Single project |
| `POST /api/v3.1/project/usage/{entity_type}` | `x-api-key` *(or cookie)* | Single project |

The org endpoints accept a `project_id` filter so you can slice by project without rotating keys.

## Entity types

| Entity type | What it counts |
| - | - |
| `tool_calls` | Every tool execution (successful or failed) |
| `sessions` | Sessions created |

## Summary

Totals across entity types for a time window.

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
>
> summary = composio.experimental.usage.summary(
>     from_=1744848000000,
>     to=1744934400000,
>     entity_types=["tool_calls", "sessions"],
> )
> print(summary.entities)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
>
> const summary = await composio.experimental.usage.summary({
>   from: 1744848000000,
>   to: 1744934400000,
>   entityTypes: ['tool_calls', 'sessions'],
> });
> console.log(summary.entities);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/project/usage/summary \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "from": 1744848000000,
>     "to": 1744934400000,
>     "entity_types": ["tool_calls", "sessions"]
>   }'
> ```

Response:

```json theme={null}
{
  "entities": {
    "tool_calls": { "unit": "count", "total_quantity": "142", "event_count": 142 },
    "sessions":  { "unit": "count", "total_quantity": "8",   "event_count": 8 }
  }
}
```

### Summary parameters

| Field | Type | Default | Notes |
| - | - | - | - |
| `from` | number | 30 days ago | Epoch milliseconds |
| `to` | number | now | Epoch milliseconds |
| `entity_types` | string\[] | all | Subset of `tool_calls`, `sessions` |
| `filters.user_id` | string\[] | — | Filter events by initiating user |
| `filters.session_id` | string\[] | — | Filter events by session |
| `filters.project_id` | string\[] | — | Only meaningful on org endpoints; ignored on project endpoints |

## Breakdown

One entity type, grouped by a dimension. Useful for answering "top N" questions.

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
>
> breakdown = composio.experimental.usage.breakdown(
>     "tool_calls",
>     from_=1744848000000,
>     to=1744934400000,
>     group_by="toolkit_slug",
>     order_by="total_quantity",
>     order_direction="desc",
>     limit=10,
> )
> print(breakdown.groups)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
>
> const breakdown = await composio.experimental.usage.breakdown('tool_calls', {
>   from: 1744848000000,
>   to: 1744934400000,
>   groupBy: 'toolkit_slug',
>   orderBy: 'total_quantity',
>   orderDirection: 'desc',
>   limit: 10,
> });
> console.log(breakdown.groups);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "from": 1744848000000,
>     "to": 1744934400000,
>     "group_by": "toolkit_slug",
>     "order_by": "total_quantity",
>     "order_direction": "desc",
>     "limit": 10
>   }'
> ```

Response:

```json theme={null}
{
  "entity_type": "tool_calls",
  "unit": "count",
  "total_quantity": "142",
  "event_count": 142,
  "groups": [
    { "key": "github", "total_quantity": "80", "event_count": 80 },
    { "key": "slack",  "total_quantity": "62", "event_count": 62 }
  ]
}
```

### Breakdown `group_by` options

| Entity | Org scope | Project scope | Default |
| - | - | - | - |
| `tool_calls` | `tool_slug`, `toolkit_slug`, `connected_account_id`, `user_id`, `session_id`, `project_id` | same minus `project_id` | `tool_slug` |
| `sessions` | `user_id`, `project_id` | `user_id` | `user_id` |

### Breakdown parameters

| Field | Type | Default | Notes |
| - | - | - | - |
| `from` | number | 30 days ago | Epoch ms |
| `to` | number | now | Epoch ms |
| `group_by` | string | see table | Dimension to group by |
| `order_by` | string | `total_quantity` | One of `key`, `total_quantity`, `event_count` |
| `order_direction` | `"asc"` \| `"desc"` | `"desc"` | |
| `limit` | number | 50 | Max groups returned |
| `filters` | object | — | See Filters below |

## Filters

Filters live in a `filters` object on the request body. Each filter value is an **array of strings**, even for a single value:

* Within a single field, values are OR-combined (`user_id: ["a", "b"]` matches events for user *a or b*).
* Across fields, filters are AND-combined.

```json theme={null}
{
  "filters": {
    "user_id": ["user_123", "user_456"],
    "session_id": ["sess_abc"]
  }
}
```

The `project_id` filter is only meaningful on the org-scoped endpoints. Project endpoints accept the field but ignore it (your key already pins the scope to a single project).

## Time ranges

* `from` and `to` are **epoch milliseconds**.
* `from` defaults to 30 days before `to`.
* `to` defaults to the current time.
* Maximum range: **366 days**. Longer ranges return a 400.

## Recipes

### Top 10 tools my org called last week

The Python SDK requires `COMPOSIO_API_KEY` to initialize as well as `COMPOSIO_ORG_API_KEY` for the organization-scoped request.

> [tab] Python
>
> ```python theme={null}
> import os
> import time
> from composio import Composio
>
> composio = Composio(org_api_key=os.environ["COMPOSIO_ORG_API_KEY"])
> now = int(time.time()) * 1000
> breakdown = composio.client.org.usage.retrieve(
>     "tool_calls",
>     from_=now - 604_800_000,
>     to=now,
>     group_by="tool_slug",
>     limit=10,
> )
> print(breakdown)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio({
>   apiKey: null,
>   userApiKey: null,
>   orgApiKey: process.env.COMPOSIO_ORG_API_KEY,
> });
> const now = Math.floor(Date.now() / 1000) * 1000;
> const breakdown = await composio.getClient().post<unknown>('/api/v3.1/org/usage/tool_calls', {
>   body: { from: now - 604_800_000, to: now, group_by: 'tool_slug', limit: 10 },
> });
> console.log(breakdown);
> ```

> [tab] API
>
> ```bash theme={null}
> WEEK_AGO=$(( $(date +%s) - 604800 ))000
> NOW=$(date +%s)000
> curl -X POST https://backend.composio.dev/api/v3.1/org/usage/tool_calls \
>   -H "x-org-api-key: $COMPOSIO_ORG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "from": '"$WEEK_AGO"',
>     "to": '"$NOW"',
>     "group_by": "tool_slug",
>     "limit": 10
>   }'
> ```

### Tool call count per user for my project this month

> [tab] Python
>
> ```python theme={null}
> import time
>
> from composio import Composio
>
> composio = Composio()
>
> now = int(time.time() * 1000)
> breakdown = composio.experimental.usage.breakdown(
>     "tool_calls",
>     from_=now - 2_592_000_000,
>     to=now,
>     group_by="user_id",
>     limit=50,
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
>
> const now = Date.now();
> const breakdown = await composio.experimental.usage.breakdown('tool_calls', {
>   from: now - 2_592_000_000,
>   to: now,
>   groupBy: 'user_id',
>   limit: 50,
> });
> ```

> [tab] API
>
> ```bash theme={null}
> MONTH_AGO=$(( $(date +%s) - 2592000 ))000
> NOW=$(date +%s)000
> curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "from": '"$MONTH_AGO"',
>     "to": '"$NOW"',
>     "group_by": "user_id",
>     "limit": 50
>   }'
> ```

### Which toolkits is a specific user using?

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
>
> breakdown = composio.experimental.usage.breakdown(
>     "tool_calls",
>     group_by="toolkit_slug",
>     filters={"user_id": ["user_abc123"]},
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
>
> const breakdown = await composio.experimental.usage.breakdown('tool_calls', {
>   groupBy: 'toolkit_slug',
>   filters: { userId: ['user_abc123'] },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "group_by": "toolkit_slug",
>     "filters": { "user_id": ["user_abc123"] }
>   }'
> ```
