Skip to main content
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.
Response:

Summary parameters

Breakdown

One entity type, grouped by a dimension. Useful for answering “top N” questions.
Response:

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

Tool call count per user for my project this month

Which toolkits is a specific user using?