Observability
Composio exposes two v3.1 REST APIs for inspecting activity in your org or project: a Logs API for individual tool execution events and a Usage API for aggregated counts. Use this page to figure out which one to call.
Which API should I use?
| I want to... | Use |
|---|---|
| Debug a specific tool execution (payloads, errors, timing) | Tool execution logs |
| See how many tool calls or sessions happened in a window | Usage summary |
| Break usage down by tool, toolkit, user, or session | Usage breakdown |
Logs record individual events and are primarily for debugging. Usage queries return aggregated counts from ClickHouse and are primarily for dashboards, billing integrations, and customer-facing analytics.
Authentication at a glance
Each endpoint family takes a specific credential. Use the right one for the scope you need.
| Endpoints | Header | Scope |
|---|---|---|
POST /api/v3.1/org/usage/summaryPOST /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/summaryPOST /api/v3.1/project/usage/{entity_type} | x-api-key (or session cookie) | Single project |
POST /api/v3.1/logs/tool_executionGET /api/v3.1/logs/tool_execution/{id} | x-api-key (or session cookie) | Single project |
The org-level usage endpoints accept a project_id filter so you can slice by project without rotating keys.
Reference
For full request/response schemas, see the auto-generated reference:
- Organization API reference — org-level usage endpoints
- Projects API reference — project-level usage endpoints and project-scoped APIs