Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 23:30 UTC
docs: add observability narrative for logs + usage APIs
Adds three pages under /docs/observability covering the v3.1 tool execution logs and usage summary/breakdown APIs, plus a sidebar entry and a dated changelog. Metrics API is descoped. Closes PLEN-1847. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
shams haroon committed
Apr 17, 2026 at 12:30 UTC
be30c1c2be63d5b8651ba520779c19662d5fd6c3
6 files changed
+422
docs/content/changelog/04-17-26.mdx
new
+29
@@ -0,0 +1,29 @@
1
+---
2
+title: "Observability APIs: tool execution logs and usage metering"
3
+description: "Query individual tool execution logs and aggregated usage counts for your org or project via v3.1 REST endpoints."
4
+date: "2026-04-17"
5
+---
6
+
7
+Two new v3.1 observability API surfaces are live.
8
+
9
+## Tool execution logs
10
+
11
+Search, filter, and paginate individual tool execution events. Use this for debugging failures, inspecting request/response payloads, and tracing user activity.
12
+
13
+- `POST /api/v3.1/logs/tool_execution` — list with filters, time range, and cursor pagination.
14
+- `GET /api/v3.1/logs/tool_execution/{id}` — full detail including request payload, response body, timings, and source metadata.
15
+
16
+Authentication: project API key (`x-api-key`) or session cookie.
17
+
18
+See the [tool execution logs guide](/docs/observability/logs).
19
+
20
+## Usage metering
21
+
22
+Aggregated counts of tool calls and sessions, sourced from ClickHouse. Summary endpoints return totals; breakdown endpoints group results by tool, toolkit, user, session, or project.
23
+
24
+- `POST /api/v3.1/org/usage/summary` and `POST /api/v3.1/org/usage/{entity_type}` — org scope (`x-org-api-key` or org JWT).
25
+- `POST /api/v3.1/project/usage/summary` and `POST /api/v3.1/project/usage/{entity_type}` — project scope (`x-api-key` or cookie).
26
+
27
+Entity types: `tool_calls`, `sessions`. Time ranges are epoch milliseconds; max range 366 days.
28
+
29
+See the [usage metering guide](/docs/observability/usage).
docs/content/docs/meta.json
+1
@@ -29,6 +29,7 @@
29
"sessions-vs-direct-execution",
30
"---Features---",
31
"projects",
32
+ "observability",
33
"single-toolkit-mcp",
34
"---Direct Tool Execution Guides---",
35
"tools-direct",
docs/content/docs/observability/index.mdx
new
+36
@@ -0,0 +1,36 @@
1
+---
2
+title: Observability
3
+description: Inspect tool execution activity and usage for your org or project.
4
+keywords: ['observability', 'logs', 'usage', 'metering', 'metrics']
5
+---
6
+
7
+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.
8
+
9
+## Which API should I use?
10
+
11
+| I want to... | Use |
12
+|---|---|
13
+| Debug a specific tool execution (payloads, errors, timing) | [Tool execution logs](/docs/observability/logs) |
14
+| See how many tool calls or sessions happened in a window | [Usage summary](/docs/observability/usage#summary) |
15
+| Break usage down by tool, toolkit, user, or session | [Usage breakdown](/docs/observability/usage#breakdown) |
16
+
17
+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.
18
+
19
+## Authentication at a glance
20
+
21
+Each endpoint family takes a specific credential. Use the right one for the scope you need.
22
+
23
+| Endpoints | Header | Scope |
24
+|---|---|---|
25
+| `POST /api/v3.1/org/usage/summary`<br/>`POST /api/v3.1/org/usage/{entity_type}` | `x-org-api-key` *(or org JWT)* | All projects in your org |
26
+| `POST /api/v3.1/project/usage/summary`<br/>`POST /api/v3.1/project/usage/{entity_type}` | `x-api-key` *(or session cookie)* | Single project |
27
+| `POST /api/v3.1/logs/tool_execution`<br/>`GET /api/v3.1/logs/tool_execution/{id}` | `x-api-key` *(or session cookie)* | Single project |
28
+
29
+The org-level usage endpoints accept a `project_id` filter so you can slice by project without rotating keys.
30
+
31
+## Reference
32
+
33
+For full request/response schemas, see the auto-generated reference:
34
+
35
+- [Organization API reference](/reference/api-reference/organization) — org-level usage endpoints
36
+- [Projects API reference](/reference/api-reference/projects) — project-level usage endpoints and project-scoped APIs
docs/content/docs/observability/logs.mdx
new
+149
@@ -0,0 +1,149 @@
1
+---
2
+title: Tool execution logs
3
+description: Search, filter, and inspect individual tool execution logs for debugging and forensics.
4
+keywords: ['logs', 'tool execution', 'debugging', 'observability']
5
+---
6
+
7
+The Logs API returns **individual tool execution events** — one record per tool call. Use it to debug failures, inspect request/response payloads, and trace specific user activity. For aggregated counts (how many tool calls happened), use the [Usage API](/docs/observability/usage) instead.
8
+
9
+All endpoints in this section require a **project API key** (`x-api-key`) or a valid session cookie.
10
+
11
+## List logs
12
+
13
+```bash
14
+curl -X POST https://backend.composio.dev/api/v3.1/logs/tool_execution \
15
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
16
+ -H "Content-Type: application/json" \
17
+ -d '{
18
+ "limit": 20,
19
+ "time_range": {
20
+ "from": 1744848000000,
21
+ "to": 1744934400000
22
+ },
23
+ "filters": [
24
+ { "field": "toolkit_slug", "operator": "==", "value": "gmail" },
25
+ { "field": "status", "operator": "==", "value": "failed" }
26
+ ]
27
+ }'
28
+```
29
+
30
+The response contains a page of log entries and a `next_cursor`:
31
+
32
+```json
33
+{
34
+ "logs": [
35
+ {
36
+ "id": "log_-jRTWClpBoVo",
37
+ "timestamp": "2026-04-17T10:25:00.000Z",
38
+ "type": "tool.execution",
39
+ "status": "failed",
40
+ "level": "error",
41
+ "message": "GMAIL_SEND_EMAIL failed: invalid recipient",
42
+ "metadata": { /* tool, toolkit, user_id, connected_account_id, ... */ },
43
+ "metrics": { "duration_ms": 202 },
44
+ "parent": null
45
+ }
46
+ ],
47
+ "next_cursor": "eyJwYWdlIjoyfQ=="
48
+}
49
+```
50
+
51
+Pass `next_cursor` back as `cursor` on the next request to paginate. When `next_cursor` is `null`, you've reached the end.
52
+
53
+### Filter fields
54
+
55
+Pass one or more filters in the `filters` array. Filters are **AND**-combined.
56
+
57
+| Field | What it matches |
58
+|---|---|
59
+| `tool_slug` | The specific tool that was called (e.g. `GMAIL_SEND_EMAIL`) |
60
+| `toolkit_slug` | The toolkit (e.g. `gmail`, `slack`, `github`) |
61
+| `connected_account_id` | The connected account used for the call |
62
+| `auth_config_id` | The auth config (integration) behind the connected account |
63
+| `status` | `success` or `failed` |
64
+| `user_id` | Entity that initiated the call |
65
+| `session_id` | Tool router session, if routed through a session |
66
+| `sandbox_id` | Sandbox the call ran in, if applicable |
67
+| `request_id` | Request ID (useful for correlating with your own logs) |
68
+| `log_id` | Exact log ID (equivalent to the detail endpoint) |
69
+
70
+### Operators
71
+
72
+| Operator | Meaning |
73
+|---|---|
74
+| `==` | Exact match |
75
+| `!=` | Not equal |
76
+| `contains` | Substring match |
77
+| `not_contains` | Substring does not match |
78
+
79
+### Parameters
80
+
81
+| Field | Type | Default | Notes |
82
+|---|---|---|---|
83
+| `limit` | number | `20` | Max 100 |
84
+| `cursor` | string \| null | `null` | Opaque pagination token from previous response |
85
+| `filters` | array | `[]` | AND-combined |
86
+| `time_range.from` | number | — | Epoch milliseconds |
87
+| `time_range.to` | number | — | Epoch milliseconds |
88
+
89
+## Get a single log
90
+
91
+Fetch one log by ID to get the **full** payload, including request/response bodies, timing breakdowns, and source metadata:
92
+
93
+```bash
94
+curl https://backend.composio.dev/api/v3.1/logs/tool_execution/log_-jRTWClpBoVo \
95
+ -H "x-api-key: YOUR_PROJECT_API_KEY"
96
+```
97
+
98
+The detail response includes everything from the list shape plus:
99
+
100
+- `timings` — `start_time` and `end_time` in epoch ms
101
+- `context` — `session_id`, `trace_id`, `request_id`
102
+- `source` — `host` (e.g. `mcp`, `sdk`, `api`), `framework`, `language`
103
+- `data` — the full request payload and response body
104
+
105
+This is the endpoint to call when you need to reconstruct *exactly* what happened — e.g. when debugging a 500 from a user report.
106
+
107
+## Recipes
108
+
109
+### Find failed Gmail tool calls in the last hour
110
+
111
+```bash
112
+NOW=$(date +%s)000
113
+HOUR_AGO=$(( $(date +%s) - 3600 ))000
114
+curl -X POST https://backend.composio.dev/api/v3.1/logs/tool_execution \
115
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
116
+ -H "Content-Type: application/json" \
117
+ -d "{
118
+ \"time_range\": { \"from\": ${HOUR_AGO}, \"to\": ${NOW} },
119
+ \"filters\": [
120
+ { \"field\": \"toolkit_slug\", \"operator\": \"==\", \"value\": \"gmail\" },
121
+ { \"field\": \"status\", \"operator\": \"==\", \"value\": \"failed\" }
122
+ ]
123
+ }"
124
+```
125
+
126
+### Get failures for a specific user
127
+
128
+```bash
129
+curl -X POST https://backend.composio.dev/api/v3.1/logs/tool_execution \
130
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
131
+ -H "Content-Type: application/json" \
132
+ -d '{
133
+ "filters": [
134
+ { "field": "user_id", "operator": "==", "value": "user_abc123" },
135
+ { "field": "status", "operator": "==", "value": "failed" }
136
+ ]
137
+ }'
138
+```
139
+
140
+### Fetch a single log's full request/response
141
+
142
+```bash
143
+curl https://backend.composio.dev/api/v3.1/logs/tool_execution/log_-jRTWClpBoVo \
144
+ -H "x-api-key: YOUR_PROJECT_API_KEY"
145
+```
146
+
147
+## Reference
148
+
149
+See the [Projects API reference](/reference/api-reference/projects) for the generated schema.
docs/content/docs/observability/meta.json
new
+4
@@ -0,0 +1,4 @@
1
+{
2
+ "title": "Observability",
3
+ "pages": ["index", "logs", "usage"]
4
+}
docs/content/docs/observability/usage.mdx
new
+203
@@ -0,0 +1,203 @@
1
+---
2
+title: Usage metering
3
+description: Query aggregated tool call and session counts for your org or project, with rich filtering and breakdown options.
4
+keywords: ['usage', 'metering', 'analytics', 'billing', 'observability']
5
+---
6
+
7
+The Usage API returns **aggregated counts** of tool calls and sessions, sourced from ClickHouse. Use it to power billing dashboards, customer-facing analytics, or internal utilization reports. For individual events, use the [Logs API](/docs/observability/logs).
8
+
9
+There are two query shapes:
10
+
11
+- **Summary** — totals across one or more entity types in a time window.
12
+- **Breakdown** — one entity type, grouped by a dimension (tool, user, session, etc.).
13
+
14
+Each shape comes in an org-scoped and a project-scoped flavor.
15
+
16
+## Authentication
17
+
18
+| Endpoint | Header | Scope |
19
+|---|---|---|
20
+| `POST /api/v3.1/org/usage/summary` | `x-org-api-key` *(or org JWT)* | All projects in your org |
21
+| `POST /api/v3.1/org/usage/{entity_type}` | `x-org-api-key` *(or org JWT)* | All projects in your org |
22
+| `POST /api/v3.1/project/usage/summary` | `x-api-key` *(or cookie)* | Single project |
23
+| `POST /api/v3.1/project/usage/{entity_type}` | `x-api-key` *(or cookie)* | Single project |
24
+
25
+The org endpoints accept a `project_id` filter so you can slice by project without rotating keys.
26
+
27
+## Entity types
28
+
29
+| Entity type | What it counts |
30
+|---|---|
31
+| `tool_calls` | Every tool execution (successful or failed) |
32
+| `sessions` | Tool router sessions created |
33
+
34
+## Summary
35
+
36
+Totals across entity types for a time window.
37
+
38
+```bash
39
+curl -X POST https://backend.composio.dev/api/v3.1/project/usage/summary \
40
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
41
+ -H "Content-Type: application/json" \
42
+ -d '{
43
+ "from": 1744848000000,
44
+ "to": 1744934400000,
45
+ "entity_types": ["tool_calls", "sessions"]
46
+ }'
47
+```
48
+
49
+Response:
50
+
51
+```json
52
+{
53
+ "entities": {
54
+ "tool_calls": { "unit": "count", "total_quantity": "142", "event_count": 142 },
55
+ "sessions": { "unit": "count", "total_quantity": "8", "event_count": 8 }
56
+ }
57
+}
58
+```
59
+
60
+### Summary parameters
61
+
62
+| Field | Type | Default | Notes |
63
+|---|---|---|---|
64
+| `from` | number | 30 days ago | Epoch milliseconds |
65
+| `to` | number | now | Epoch milliseconds |
66
+| `entity_types` | string[] | all | Subset of `tool_calls`, `sessions` |
67
+| `filters.user_id` | string \| string[] | — | Filter events by initiating user |
68
+| `filters.session_id` | string \| string[] | — | Filter events by tool router session |
69
+| `filters.project_id` | string \| string[] | — | Only meaningful on org endpoints; ignored on project endpoints |
70
+
71
+## Breakdown
72
+
73
+One entity type, grouped by a dimension. Useful for answering "top N" questions.
74
+
75
+```bash
76
+curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
77
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
78
+ -H "Content-Type: application/json" \
79
+ -d '{
80
+ "from": 1744848000000,
81
+ "to": 1744934400000,
82
+ "group_by": "toolkit_slug",
83
+ "order_by": "total_quantity",
84
+ "order_direction": "desc",
85
+ "limit": 10
86
+ }'
87
+```
88
+
89
+Response:
90
+
91
+```json
92
+{
93
+ "entity_type": "tool_calls",
94
+ "unit": "count",
95
+ "total_quantity": "142",
96
+ "event_count": 142,
97
+ "groups": [
98
+ { "key": "github", "total_quantity": "80", "event_count": 80 },
99
+ { "key": "slack", "total_quantity": "62", "event_count": 62 }
100
+ ]
101
+}
102
+```
103
+
104
+### Breakdown `group_by` options
105
+
106
+| Entity | Org scope | Project scope | Default |
107
+|---|---|---|---|
108
+| `tool_calls` | `tool_slug`, `toolkit_slug`, `connected_account_id`, `user_id`, `session_id`, `project_id` | same minus `project_id` | `tool_slug` |
109
+| `sessions` | `user_id`, `project_id` | `user_id` | `user_id` |
110
+
111
+### Breakdown parameters
112
+
113
+| Field | Type | Default | Notes |
114
+|---|---|---|---|
115
+| `from` | number | 30 days ago | Epoch ms |
116
+| `to` | number | now | Epoch ms |
117
+| `group_by` | string | see table | Dimension to group by |
118
+| `order_by` | string | `total_quantity` | One of `key`, `total_quantity`, `event_count` |
119
+| `order_direction` | `"asc"` \| `"desc"` | `"desc"` | |
120
+| `limit` | number | 50 | Max groups returned |
121
+| `filters` | object | — | See Filters below |
122
+
123
+## Filters
124
+
125
+Filters live in a `filters` object on the request body. Each filter value can be a **single string** or an **array of strings**:
126
+
127
+- Within a single field, values are OR-combined (`user_id: ["a", "b"]` matches events for user *a or b*).
128
+- Across fields, filters are AND-combined.
129
+
130
+```json
131
+{
132
+ "filters": {
133
+ "user_id": ["user_123", "user_456"],
134
+ "session_id": "sess_abc"
135
+ }
136
+}
137
+```
138
+
139
+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).
140
+
141
+## Time ranges
142
+
143
+- `from` and `to` are **epoch milliseconds**.
144
+- `from` defaults to 30 days before `to`.
145
+- `to` defaults to the current time.
146
+- Maximum range: **366 days**. Longer ranges return a 400.
147
+
148
+## Recipes
149
+
150
+### Top 10 tools my org called last week
151
+
152
+```bash
153
+WEEK_AGO=$(( $(date +%s) - 604800 ))000
154
+NOW=$(date +%s)000
155
+curl -X POST https://backend.composio.dev/api/v3.1/org/usage/tool_calls \
156
+ -H "x-org-api-key: YOUR_ORG_API_KEY" \
157
+ -H "Content-Type: application/json" \
158
+ -d "{
159
+ \"from\": ${WEEK_AGO},
160
+ \"to\": ${NOW},
161
+ \"group_by\": \"tool_slug\",
162
+ \"limit\": 10
163
+ }"
164
+```
165
+
166
+### Tool call count per user for my project this month
167
+
168
+```bash
169
+MONTH_AGO=$(( $(date +%s) - 2592000 ))000
170
+NOW=$(date +%s)000
171
+curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
172
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
173
+ -H "Content-Type: application/json" \
174
+ -d "{
175
+ \"from\": ${MONTH_AGO},
176
+ \"to\": ${NOW},
177
+ \"group_by\": \"user_id\",
178
+ \"limit\": 50
179
+ }"
180
+```
181
+
182
+### Which toolkits is a specific user using?
183
+
184
+```bash
185
+curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
186
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
187
+ -H "Content-Type: application/json" \
188
+ -d '{
189
+ "group_by": "toolkit_slug",
190
+ "filters": { "user_id": "user_abc123" }
191
+ }'
192
+```
193
+
194
+## Self-hosted deployments
195
+
196
+If your Composio instance is self-hosted **without ClickHouse enabled**, the usage endpoints return `500`. The Logs API does not depend on ClickHouse and remains available.
197
+
198
+## Reference
199
+
200
+See the auto-generated reference for full schemas:
201
+
202
+- [Organization API reference](/reference/api-reference/organization) — org-level usage endpoints
203
+- [Projects API reference](/reference/api-reference/projects) — project-level usage endpoints