Organization

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.

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 reference page.

Authentication

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

Entity types

Summary

Totals across entity types for a time window.

from composio import Composio

composio = Composio()

summary = composio.experimental.usage.summary(
    from_=1744848000000,
    to=1744934400000,
    entity_types=["tool_calls", "sessions"],
)
print(summary.entities)

Response:

{
  "entities": {
    "tool_calls": { "unit": "count", "total_quantity": "142", "event_count": 142 },
    "sessions":  { "unit": "count", "total_quantity": "8",   "event_count": 8 }
  }
}

Summary parameters

Breakdown

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

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)

Response:

{
  "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

Breakdown parameters

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.

{
  "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.

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)

Tool call count per user for my project this month

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,
)

Which toolkits is a specific user using?

from composio import Composio

composio = Composio()

breakdown = composio.experimental.usage.breakdown(
    "tool_calls",
    group_by="toolkit_slug",
    filters={"user_id": ["user_abc123"]},
)

Endpoints