@devries-cameron20 / composio Mirror · read-only / commits / be30c1c2b
Fork 0

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